6

Without going into too much extraneous detail, currently our product manual is produced using some proprietary WYSIWYG editor, which has a bunch of limitations. I'm considering producing the manual using pdfLaTeX instead. The main motivation for this is so we can put the copy in source control. (You can't do that when your document is just a binary blob.)

Doing this is going to require a whole heap of work, so before I even start this I have to ask: Is LaTeX the correct tool for the job? Or would I be better off some other document technology? (E.g., DocBook ⇒ XSLT ⇒ XML-FO ⇒ PDF or something.)

We want our product manual to look like a trendy article in a glossy magazine, and our graphics department have done an excellent job of achieving that look. Obviously management won't accept anything that looks worse than what we already have.

LaTeX is of course excellent at producing really professional-looking academic publications. But to our target audience, that just looks "scary". We don't want customers thinking you need a PhD to understand our software. Hence the current manual has huge sans-serif fonts, liberal splashes of colour, and varying page layouts to make it not look like a "wall of text". And, being a software manual, it has a lot of screenshots (frequently featuring complicated call-outs with arrows).

I have no doubt that if you put enough experts in a room and hit it hard enough, you can probably make TeX render just about anything. But something being possible isn't the same as being easy. And saying that TeX can do something isn't the same as saying it's the best tool for the job &mdash or even the right tool for the job.

So what do we think, folks? Is TeX a good tool for this, or is there something else out there that's likely to be a better fit?

  • 1
    It is difficult to answer this question, as we have not seen an example how it should like. But I dare say, that LaTeX should perhaps not be the first choice for a glossy magazine, although there have been a lot of enhancements in the past. – user31729 Jan 23 '15 at 19:36
  • 2
    this isn't quite the same subject matter, but at tug 2011, there was a presentation on "Typesetting fancy multilingual phrase books with LuaTeX"; this was recorded on video, which should be accessible from the linked page. another example, published in tugboat is "How to make a product catalog that doesn't look like a dissertation". maybe those will give you some ideas. – barbara beeton Jan 23 '15 at 19:52
  • 4
    "[V]arying page layouts" might be the biggest drawback if you want to use some form of TeX: *TeX likes uniform page layouts. Changing the textblock on each page or every couple of pages will require (afaik) frequent manual intervention (e.g., special boxes here, two-column stuff there, wider margins on that page, skinny ones with a big picture on this page, etc., etc.). I suppose it depends on your idea of what constitutes 'easy'.... – jon Jan 23 '15 at 20:04
  • 3
    I suspect, though I am not sure, that there is going to be significant tension between the 2 desiderata you mention. That is, the tools which are best suited for producing documents from plain text source, which is ideal for version control, are not going to be the ones which are best suited to laying out pages in the ways you describe. That is, they are not going to be the most straightforward or intuitive tools for doing it, and they are going to require a good deal of manual intervention. They are unlikely to be tools the marketing department will like working with. (Unless you have an... – cfr Jan 23 '15 at 23:02
  • 2
    ... unusual marketing department composed of either TeX-nicians or masochists.) the kinds of layouts you describe are not very easy to define in plain text (call-outs, for example), and frequent changes of page layout are best done in light of the content of those pages, which means more mucking around when not using a GUI. That said, flowfram might be of interest. But note the caveats in its documentation: it gets TeX to do things TeX was not designed to do, and that depends on performing major surgery on the output routine. – cfr Jan 23 '15 at 23:05
3

To the extent that my slightly vague question admits an "answer"...

I spent the last several days trying to recreate the existing document using LaTeX. This has been broadly successful. As a result of many hours of study, I have discovered:

  • There exists something called XeTeX, which allows me to use the same expensive commercial font that the existing document has. (Sadly this also makes everything take 200x longer to compile, but hey...)

  • I find something called tikz which allows me to draw fancy multi-coloured borders, rounded corners, callouts, etc. with comparative ease.

  • Using the geometry package, I was able to reduce the generous LaTeX page margins to the meager slithers that glossy documents seem to have.

  • Using fancyhdr I managed to edit the page headers and footers to look like how I want (rather than the LaTeX defaults). I also managed to colour in the outside page margins. (I was particularly worried about TeX being unable to do that, but again TikZ managed to fix it.)

  • Using tocloft I was able to match the table of contents in the original document. (In particular, setting chapter titles in a different colour to everything else to make them stand out.)

  • Using titlesec I was able to replace the very academic-looking chapter headings with something much more glossy-looking.

  • I had to resort to manually tweaking TeX lengths to get paragraphs with vertical spaces rather than horizontal indents. But it wasn't too hard.

So far, the resulting (unfinished) document looks pretty damned similar to the original. However, I haven't yet tried inserting any screenshots, nor labelling them up. Inserting a picture shouldn't be a problem, but drawing arrows to the correct parts might be fun. However, knowing now that TikZ exists, it should be just a case of figuring out the correct coordinates (which only needs to be done once). In short, I'm fairly confident it can be done, and can be fairly containable. (Then again, I haven't actually done it yet, so...)

In summary: Yeah, you can definitely make something kinda shiny with LaTeX. Maybe not as immaculate as what our graphics department could produce, but pretty damned good. (And without needing to micro-manage page-breaks, manually keep fonts / margins / page titles consistent, and so forth.)


Edit:

Some people wanted to see the actual document. Unfortunately I have to obscure all the text, which makes it a bit difficult to tell what the thing actually looks like! But here is a heavily blurred image of the opening chapter of the manual:

Original manual

And here is what my new version looks like:

New manual

It looks a bit ugly because the Lorem Ipsum paragraphs are all so long! But with the actual document text, it looks pretty similar, actually. And when I get access to the actual commercial font on my work PC, it should look pretty much identical.

  • 1
    Could you perhaps post a screenshot of the original and your recreation? – Argo Jan 31 '15 at 18:55
  • @Argo Yeah, I'll see if I can arrange that... – MathematicalOrchid Jan 31 '15 at 19:31
  • 1
    You may be interested in tex.stackexchange.com/a/9562/17423 for figuring out the right coords. If you have an image-analysis toolchain, you could even come up with the coordinates dynamically. – Sean Allred Jan 31 '15 at 20:17
  • 1
    @SeanAllred Yeah. Well, I guess I could just ask our application what coordinates it's drawn the widgets at. In fact, come to think of it... I can query that with AT-SPI. Maybe I can automate the entire screen-shot capture / coordinate capture process... Hmm. – MathematicalOrchid Feb 1 '15 at 12:49
  • 1
    @EthanBolker I should perhaps also point out that this website has been extremely useful over the past few days. Almost every random bug and glitch I came across was solved by a quick Google search, leading to somebody else who has already asked the same question here. Naturally, I up-voted all the Qs and As that helped me. ;-) – MathematicalOrchid Feb 1 '15 at 21:57

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.