6

I am trying to devise a (possibly easy) way to replace our documentation system.

Currently we are bound to two different and apparently irreconcilable systems:

  • internally we use a wiki system based on textile.
  • all external documentation is MSWord formatted.

Both systems have (strong) shortcomings:

  • Textile cannot really produce professionally-looking documents (and all "converters" actually suck) as it is meant to produce html output.
  • MSWord can produce "nice" PDFs, but it leaves a lot of leeway to writer and, most important, it's hard to automatically produce documentation (we use a lot of code generation which could be used also to produce tables and such to be included into docs).

LaTeX is surely capable of delivering the kind of (PDF) documents we need (front page, custom header and footer, page watermark and such) without resorting to MS stuff.

I have a certain amount of (outdated) knowledge about LaTeX and I think I could manage to setup a suitable page template and some special-purpose code generator for our needs.

Question is: what is the currently advised page layout package to use for such a purpose?

I used "memoir" to write my previous-life documentation (book, actually) generator; is it still a valid choice? Should I stick to "plain" styles with helper classes (e.g.; fancyhdr)? There are so many packages I am a bit lost and I have troubles understanding what is "current" and what is "outdated".

Please note i do not want to start a holy war.

Bottom line: I would like to use some simple markup language (textile would be best choice because we already use it) to produce some code to ve inserted in a standard template (possibly hand-crafted) in order to produce "MSWord-quality" documentation (PDF).

I am fully prepared to write code to parse markup and to generate reasonably complex constructs.

I would like to avoid losing time exploring dead ends.

UPDATE: Clarification as suggested by @marmot:

What I am aiming at is:

  • Prepare a custom Document template with our specifications; these include:
    • Specific font selection
    • Front page with customer logo
    • Header with several logo images
    • Footer with Title, revision and page "# of ##"
    • A background (watermark) image.
    • Table of revisions
    • Table of content
    • Definition of "standard" Table style
    • Definition of "standard" multi-level enumerate/itemize lists.
    • Definition of "standard" Chapter, Section, ... aspect (numbered).
  • Be able to fill template with "blobs" produced from Textile (or markdown) snippets (possibly extracted from code or programmatically produced).
  • Textile and similar markups are mainly geared toward web-page generation; that's not my need; I need find (or write) some suitable converter. Luckily I need a very standardized output.
  • Some images should be produced by PlantUML, but that shouldn't be a problem as PlantUML is starting LaTeX support.
  • 6
    +1 for "Please note i do not want to start a holy war." ;-) – marmot Aug 6 '18 at 21:42
  • 2
    You might want to consider using pandoc which can convert Textile to PDF using LaTeX as the backend. If you're happy with memoir I would probably stick to it. Its only possible downside is that it's more aimed at books than smaller docs. It's a great class, and well maintained. Using it with pandoc might take a little bit of setup. In terms of what's outdated, I would say most of the core packages you're familiar with are still likely to be perfectly usable. The biggest new innovation has been in bibliography generation (biblatex) and graphics (TiKZ). – Alan Munn Aug 6 '18 at 22:00
  • 1
    On mimicking Word standard styles, see Change section fonts. (This uses titlesec but you could implement it just as easily in memoir). You might want to consider using XeLaTeX or LuaLaTeX as the engine anyway to gain access to system fonts (and therefore match existing Word documents more easily). – Alan Munn Aug 6 '18 at 22:07
  • @marmot: Textile and similar markups are mainly geared toward web-page generation; that's not my need; I need to produce "manual-quality" PDF documentation, with logo(s) in header, revisions in footer, front page with customer logo, lots of tables, multi-level subsections, plantuml-generated graphs, images and background image; all this can be easily(?) achieved with latex, but NOT with markups (not even doxygen), so I was playing with the idea of preparing a "standard" template to be filled with some content (semi)automatically generated from Textile. – ZioByte Aug 6 '18 at 22:17
  • 1
    There is the wordlike package. I have never used it though, so I don't know whether it fits your requirements. – Henri Menke Aug 6 '18 at 22:37
2

This answer will focus on the choice of packages in the first part (the LaTeX part) and will mention some other options in the second.

Question is: what is the currently advised page layout package to use for such a purpose?

Basically you are in the position to choose between package "ecosystems":

  • There are the default classes like article, book, report etc. which are very flexible and may achieve layouts like the one you describe by loading foreign packages like fancyhdr.
  • You may choose KOMA-Script (classes like scrartcl, scrreprt, scrbook etc.). It allows very complex layouts with layers and all that fancy extras by packages like scrlayer-scrpage.
  • And of course there is memoir which is still a good choice for custom styling. Please note that memoir is not as modular as the other choices are, but you may concentrate on reading one manual.

That said I would personally choose KOMA nowadays, but at this point I do not want to start a holy war, so really that is up to you. Regardless of your choice you will be able to create a simple template as you wanted to create.

Apart from packages there is the important choice of engines. Of course you may go with pdflatex, but you will miss many important features. As LuaTeX has matured I would recommend using it, because you will gain access to OpenType fonts, packages like markdown and most importantly the scripting language Lua which has access to many TeX components in this case.

So to address your update: the aforementioned package and engine decisions already allow you to use specific fonts, a custom title page, custom headers and footers (for the revision you need a data source, but that's not that hard, for the page numbering you want you should have a look at the lastpage package). If you choose the KOMA ecosystem the layering also allows you to add watermarks (otherwise you might need a package).

Depending on how your revisions are defined (git?) you may use LuaTeX's Lua integration to parse the command line output of your current versioning tools (they probably provide some sort of history). Displaying this in a toc-like manner is not that hard.

Considering your requirements for standard styles you might want to use enumitem for list environments (itemize, enumerate, description or some own environments). Altering the default style of sectioning commands is also pretty easy, KOMA does provide own commands for this (I believe memoir as well) and for the standard classes packages like titlesec are quite flexible.

A bit more difficult is the default table layout. The cellprops package tries to address this, but is quite new and I haven't tested it extensively, but of course defining an own environment for tabular material which has a uniform style is not that hard.

Bottom line: I would like to use some simple markup language (textile would be best choice because we already use it) to produce some code to ve inserted in a standard template (possibly hand-crafted) in order to produce "MSWord-quality" documentation (PDF).

So this is part two and I will not propose anything LaTeXy in this part. You said you are already using textile. That is great as it produces html which can be transformed to xml – with reasonable effort. Hence you have a good data source after only one extra step.

And instead of using LaTeX I would recommend that you have a look at ConTeXt. Its MkIV is based on LuaTeX and you have all the advantages of modern fonts, a layering system, PDF production out of the box etc. (including options for everything I mentioned in the part about LaTeX). Furthermore you may "easily" produce PDF/A if the documentation should be produces for archiving. That should easily hold for "MSWord-quality".

But still why do I recommend ConTeXt here? It has XML parsing abilities. As such you may not have to write as much code as you might have to with LaTeX. You will find examples for this online, e.g. in documents like this.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.