Hacker News Reader

Comment by hyperbovine | Hacker News Reader

Wow, this is just so far off the mark I don't even know where to begin. LaTeX excels in three areas that are crucial for writing complex documents -- cross references, citations, and indexing. You clearly have not had to endure the house of horrors that is the MS Word ToC, or trying to get autonumbering working as you wish for sections, figures, and tables, or managing a large (100s of pages) multipart document, or any one of a bazillion other little asspains that crop up when forced to use Word for a nontrivial task like maintaining documentation for a large complex project. And point #1 is a complete straw man, setting up a TeX env takes 20 minutes and the basic doc format has not changed since the 1990s at least.

View on HN

Anecdote about LibreOffice 4.2.8.2: Due to a bug, LibreOffice was generating incorrect page numbers in the table of contents of a 80-page document: some sections were 1 page off, even right after I clicked to manually regenerate the TOC.

It was very frustrating, because I noticed it just a few hours before the deadline. To work around of this bug, I had to insert manual page breaks (mostly randomly), and I had to make the vertical margins of the TOC pages smaller.

LaTeX has always generated the correct numbers in the last 25 years I've been using it. And if I got something unexpected, I was able to fix it for good (without document-specific hacks such as manual page breaks) by adding some macro calls. With LibreOffice and Microsoft Office, getting such a fix ready in 1 hour is hopeless for me, so I'll either miss the deadline or I hand in something incorrect and unprofessional.

Also: LibreOffice doesn't support character formatting (of a few words only) in the ToC. LibreOffice doesn't support omitting a few select sections from the ToC. LaTeX supports both.

I thought Latex was superior to Word in every way than I had a colleague that knew Word. Word if you learn it is just fine generating a ToC or autonumbering sections, figures, and tables.

In practice, Markdown is better than either for documentation that isn't printed. It's easier to edit, can be viewed with a plain text editor, and has a minimal learning curve.

> I thought Latex was superior to Word in every way than I had a colleague that knew Word. Word if you learn it is just fine generating a ToC or autonumbering sections, figures, and tables.

No, it doesn't work well even if you know what you're doing. It's much better than when blindly trying to hack your way through, but there are still so many weird quirks it does which you always have to spend a lot of time on.

I would say it works well if you know what you are doing, but in a shared document there is always some dumb ass in the team that does some manual formatting like using the bold-button instead of changing header type, or remove a link from an image. Then the all the references and indexes are beyond repair with the only way to salvage the document is to slowly, meticulously and painfully go through it in this outline-view and try to identify what should be a header and what should not.

If only there was a way to create a Word document that forbids manual formatting it could actually be usable.

"Word if you learn it is just fine generating a ToC or autonumbering sections, figures, and tables." : but can it do this? -- [Common Lisp Quick Reference](http://clqr.boundp.org/clqr-a4-booklet-all.pdf)

Wow, that's beautifully set!

> And point #1 is a complete straw man, setting up a TeX env takes 20 minutes and the basic doc format has not changed since the 1990s at least.

Well, I had to re-encode my documents twice in that time, once to isolatin1, and once to Unicode, because I was writing in Spanish and German. But it was actually fun to figure how to make that translation happen completely automated and happen in a few seconds.

You don't know the requirements of documentation that we're writing. They don't need a table of contents. They don't need an index. They don't need citations. They don't need math symbols. They don't need tables more complex than a word processor can create. We require no features which your typical academic or research paper requires. We are documenting processes with screenshots that users can refer to in order to accomplish specific tasks. Only a dozen of them are more than 25 pages, and in Word if you keep your document formatting simple and use the built-in styles for headings, the Navigation Pane serves as a hyperlinked ToC. None of these documents should be printed because the processes can change, so beyond basic structure, layout isn't particularly important.

Furthermore, our documents can't be written in LaTeX because half the people responsible for maintaining them come from a non-technical background with no experience in programming. No, we are not going to inflict a WYSIWYG LaTeX editor -- all of which are far less usable than Word -- on people just because some technical people want to pretend they're programming.

Nevertheless, our CS interns invariably say, "Why don't we use LaTeX for this documentation?" I understand why they want to. They use LaTeX for all their papers. However, it is inappropriate in our situation and has gotten to be a rather irritating question.

> You don't know the requirements of documentation that we're writing

Yet you seem happy to prescribe your (extremely limited) views on everyone else without knowing their situation.

Good for you if all your documentation requirements are trivial, and I'm sorry to hear that your team cannot cope with trivial software installs or simple markup. Maybe the problems lie not with LaTeX...

Reply on news.ycombinator.com