Last year I joined the Canberra Society of Editors, CSE. Since I am not a professional editor (though I have acted in the role for a few publications) and I have no formal qualifications, I joined as an Associate Member. When I signed up the webform asked me what I might contribute to the society. I mentioned the things I knew something about, and newsletter editor Farid Rahimi came back suggesting that a message to the society newsgroup asking whether people would like to be introduced to LaTeX might be worthwhile. We sent the message, got a handful of responses, and, well…I wrote an article. It is here, the June 2015 issue.
Writing an article for a magazine whose readership consists entirely of people who specialise in finding errors in written English is scary. In the end I just had to forget about the audience, write it for a general reader, and then check it over fairly carefully. Fairly…
I decided that the topic was so wide that the best approach was to outline LaTeX’s main capabilities—logical mark-up, defining your own commands, cross referencing, good default text flow—then focus on LaTeX’s strengths and weaknesses as they pertain to editing. The change tracking facilities of modern WYSIWYG programs, most obviously Word, are very widely used tools—many modern editing textbooks have whole chapters walking the reader through the use of Word’s reviewing tools. Grammar checkers are also an issue. Equivalents to both of these tools can be found in the LaTeX universe, but they do not operate in familiar ways or provide like-for-like functionality. These things are real issues for editors.
In order to cover the ground I felt was important, yet not occupy the whole newsletter for several issues, I broke the content into two parts, a high-level review that was the actual article, and an example document that implemented many of the qualities to which I referred. The latter is available on my little download page here (cse_example.zip), a file bundle that includes all the source files needed to compile the document, including a gnuplot script that produces a graphic included using the gnuplot-lua-tikz package, a bibliography, mathematics, inputted files, and so on.
Installing LaTeX packages and compiling their documentation from source has some tricks which often don’t get documented. I mean, they are documented somewhere but not when and where you need them.
So here is the process.
(1) You get your ‘source’ file, possibly a something like packagename.source.zip, containing packagename.dtx and package.ins.
(2) You LaTeX the ins file and you get the sty file (and maybe some ancillary files) — the actual LaTeX macros. You copy this file/these files to somewhere like \home\username\texmf\tex\latex\packagename\.
(3) You run mktexlsr or texhash or whatever and you can use the macros. Great.
(4) You LaTeX the dtx file to get the documentation. It produces a dvi or pdf file (depending on whether you run latex or pdflatex) plus maybe an idx and maybe a glo file. What the hell?
(5) You take a guess and run makeindex packagename and it seems to work. If you’re like me until recently, you’ve got no idea what to do with the glo file and you leave it for now.
(6) You run LaTeX on the dtx and and yes indeed it compiles but the index is all overlapped with itself and weird looking and you still don’t know what to do with the glossary.
OK. this is what I found I ought to do. Apologies if it is obvious to you, it is not obvious to me.
After step (4) above, you type this:
makeindex -s gind.ist packagename.idx
makeindex -s gglo.ist -o packagename.gls packagename.glo
THEN latex it again a few times.
What the -s flag does is tell makeindex what index style (ist) file to use. In the second call, since it defaults to looking for index files, you have to tell it (a) to use the gglo.ist style since it is formatting a glossary and (b) pull in the glo file and output a gls file.
Any dtx file that has a glossary and/or an index should be processed in this way, but most of them don’t actually tell you.