Are there good practice rules for writing clean LaTeX? Something like PEP8 for Python. Examples:
- spaces or tabs (not a troll) ;
- how many columns before wrapping (80 for PEP8 compliant Python) ;
- something about comments ;
- etc.
[Tex/LaTex] Good practice rules for writing clean LaTeX
best practices
Related Solutions
Posting this as an answer because it is too long for a comment, but I do not aim at exhaustivity (or objectivity, as a matter of fact).
My first suggestion would be, whatever you do regarding the choice of terms to index, to use and abuse the | syntax in your indexing commands (either manually, or by creating your own command that does it):
It works for page ranges, by successively indexing:
\index{something|(} ... \index{something|)}
It also works for whatever formatting commands you may want to add to the page number. Essentially, you can put any control sequence name after |, provided that its last argument (if any) is the implicit page number.
For instance, when something is located in a footnote, I defined:
\newcommand{\note}[1]{#1~(\emph{n.})}
and I can then use: \index{something|note} – no backslash – which outputs:
something, 36 (n.)
This could be used to put the page number in boldface, or something of that kind. Identifying the principal reference(s) sounds like a good idea to me, though it is a matter of personal taste (some people do it, some don't).
Now, regarding your question proper, the general idea is that you should index terms where it makes the most sense and/or where the reader is most likely to look for them.
To me, this would mean that if you have an expression with a noun and an adjective, like "British imperialism", you would index:
imperialism, British, 39
and eventually (adjectives shouldn't normally be index headings):
British imperialism, see imperialism
Regarding abbreviations, the same logic could apply. Since the abbreviation stands for the full expression, it would seem logical redirect the reader there, a bit like in a glossary. So, unlike what you proposed in your question, I would be kind to the reader (if he is not strictly speaking from your field, chances are he does not remember all abbreviations), and suggest:
EIC, see East India Company (British)
East India Company (British), 45
But there could be many variants; for instance, an equally valid construct could be:
East India Company (EIC), 45
Then, there are the complex cases where you have two nouns (or words) of approximatively equal semantic weight, and it is not clear which one should be indexed. Here, it depends on the context, I suppose.
If you think that the reader could reasonably look up either term, then index both with a "see" construct.
If both terms are already indexed in their own right, for other reasons (with sub-entries perhaps), then it is almost always worthwhile to redirect the reader with a "see" construct.
Returning to my first example, while I would not necessarily (just eventually) index "British imperialism" on its own just for a "see" construct, if I already had two significant entries for "britain" and "imperialism", I would definitely write:
Britain, 2, 18-29, 23: economy, 5, 33–39; imperialism (see imperialism)
imperialism: British, 37; Dutch, 74; French, 82
I find it good practice, as far as possible, to create matching index headings; what I really mean is, consistency. If you have two things that have a similar logical structure, index them in the same way. Say, if you are indexing people's names to refer the reader to biographical information, try to construct the sub-entries in the same fashion for everyone. I am not saying they should be strictly identical, but that when similarities (in sub-entries) do occur, you should make sure they appear as such in your index.
Say, don't index:
Smith, John: Years in London, 46
and a couple of entries later:
Turner, Jack: Lived in Manchester, 32
That's inconsistent and awkward.
Here is the Chicago Manual of Style's stand on "see" references:
See references direct a reader from, for example, an informal term to a technical one, a pseudonym to a real name, an inverted term to a noninverted one. They are also used for variant spellings, synonyms, aliases, abbreviations, and so on.
The Oxford Guide to Style is substantially similar on that matter. Neither give very precise information regarding abbreviations and other complex issues, but they have great chapters on indexing proper names and punctuating index entries.
Finally, regarding indexing processes, while I agree with most of the comments so far – that most of the work takes place when you are almost done with the writing – I think there are some things you can index on the go, as "flags". If a word is so important that it makes a section heading, or that you define it in a precise way, it will be indexed under that heading anyway, so you may as well do it while writing.
This will give you bare bones for your index, which you can then improve when everything else is done. I find it helpful to print the index (with MakeIndex or on paper), then I can decide which entries are superfluous, which are lacking, which could be merged or rearranged and modify my document accordingly.
As several people have said, the only way is to write and typeset documents in LaTeX. Calculating the first 30 primes might make you a better programmer, but it is doubtful if it will make you a better LaTeX user, since it is of dubious utility to solve a problem for which LaTeX is not the right solution. If you're not sure what to write:
- Do your homework, if you have any, in LaTeX.
- Make notes and do scratch work in LaTeX rather than on paper. You will get quick at this fast, and will start to think of macros that are useful for you in particular.
- An extension of this is to write a guide to whatever you're studying in LaTeX. This is a good learning discipline, as you will be checking the depth of your understanding if you have to explain to an imagined reader. Post it online and you might get feedback too.
- Rather than recreate coursework assignments as one answer suggested, do something more useful. Find papers from the pre-LaTeX era and transcribe them. This makes them more accessible than dead-tree or bitmap scan formats (easier to access and share, easier to annotate/fix typos). Anything pre-1900 and quite a lot of early 20th century should be out of copyright (but check if you want to share your work and care about the legality) and can be shared online. There is a lot of golden-age mathematics that could be interesting to read included in this.
- If you know (especially) French, German or Russian, you could also translate old papers into English. If not you could translate classics into your own language. Post them somewhere searchable and it will inevitably be useful to someone.
- Write a book or an article on any subject in LaTeX or TeX. Even without math formulae there are hundreds of typeseting concerns that you might have to figure out.
- Write a tool to generate LaTeX documents automatically from various forms of data. Eg 'turn your WordPress blog into a book', 'add an Excel table to your LaTeX document'. If useful and polished, you can make it into a package. Even if not, you will learn loads about document structure and edge cases.
- Less hardcore: take your blog (or someone else's blog, or your fifty favorite StackExchange questions and answers, or a Project Gutenberg book, or whatever source documents) and turn it into a book manually, by copy-pasting and converting all the entries and creating the ToC, intro, appendix yourself.
- Learn literate programming and combine that algorithm to calculate the first 30 primes in your favorite language with an explanation of why it works in LaTeX. Or make literate whatever programming project you're working on already. It's a good way of writing programming tutorials.
Related Question
- [Tex/LaTex] Best practice for writing comments in LaTeX documents
- [Tex/LaTex] good practice when preparing a book for printing
- [Tex/LaTex] When to use TeX vs LaTeX for package writing
- [Tex/LaTex] Best Practice: Package for Mathematical Documents – amsmath and Beyond
- [Tex/LaTex] Best practice for plots (pgfplots, gnuplot, etc.)
Best Answer
The short answer here is simple: 'No, there are no rules akin to PEP8 or similar'.
For a longer answer, it's perhaps worth dividing up LaTeX sources into two types:
Of course, there is some overlap as one may need to 'quickly do some coding' in a preamble, but the 'nature' of a source file is usually broadly one or the other case.
For documents, the number of authors who will ever see the source is small: the key target is the typeset output. Thus it really is down to the individual(s) involved as to how they lay out their input.
For 'code', one might argue for slightly different outcomes as there is at least the potential for wider reading/reuse of sources. However, practical experience suggests that most packages have only one person actually writing the code, even for widely-used material. Where there are exceptions, most obviously the kernel but also things like
beamerorbiblatex, the 'team size' tends to be small and informal agreement is normally possible. (Usually one person has started things off so some position can be agreed based on sticking to whatever they've done.) Here of course we might use the.dtxformat for the code, which would lead to very different 'comment' outcomes to cases where the source is the package (contrast the kernel withetoolbox, for example).The one place there is a style guide for code is for
expl3: the team have written one based on the way the code has tended towards. Even there, though, there is no sense that code not following these rules is 'bad': it's much more about the content.It's important to remember that TeX is a macro expansion language, and that makes automatic 'checkers' difficult-to-impossible to implement: see Automatic style guide for LaTeX?.