Adam, On Tue, 2008-10-28 at 08:36 +1100, Adam Murdoch wrote: > Hi, > > I don't like latex. At all. I tried to like it, I really did. I just > can't do it.
You just haven't tried hard enough ;-) LaTeX is the best markup language for writing big documents, if anyone suggests DocBook/XML I shall scream and say "Don't do it, don't let XML pollute your life, don't let O'Reilly and Pragmatic Programmers indoctrinate you". Also of course PDF generation from DocBook/XML is an arcane art form whereas doing it from LaTeX is a doddle -- not to mention that most DocBook/XML PDF generation (using free-of-cost toolchains) involves transformation to LaTeX. > So, I'd like to suggest we move our documentation to something else. But what? Any mechanism that involves a binary format such as Word or ODF is a disaster from a version control perspective. FlatFile ODF generates single line files, at least in OpenOffice.org, and so is useless for version control. The only sane formats are LaTeX and XML. And XML sucks for any form of human authorship -- it is a communication notation only for consenting computers. > I've been having a play with docbook, and I quite like it. Here's what I > think are it's advantages over latex: SCREEAAMMMM... Don't do it, don't let XML pollute your life, don't let O'Reilly and Pragmatic Programmers indoctrinate you (see I said I would :-) I must immediately point out that DocBook/XML appears to have no easy way of including files by reference. This makes it very hard to construct big documents by decomposition to smaller units -- something that LaTeX handles very well. OK there are known idioms using entities for creating books from chapters, but it is including parts of code files that DocBook/XML seems to have no way of handling. > - Tool support > > Because docbook is an xml based markup language, I can point intellij at > the (well documented) schema and then get all kinds of goodness, such as > code completion, error checking, syntax highlighting, refactors, etc. > For example, Intellij understands the code includes, so I can jump back > and forth between the doc files and the samples. This is true. On the other hand Emacs with nXML is better. Actually Emacs with AucTeX is far superior because it uses LaTeX and not XML. O'Reilly push using XXE and to some extent they have a point. If you have to author DocBook/XML this does do the job. How are you doing code includes? Is it by inclusion or reference? > - 100% Java toolchain Why is this relevant? I would argue that enforcing non-functional requirements such as this is counter-productive. The tool support above is a much better line. Except that I don't want to write XML programs in IntelliJ IDEA :-) > There are a bunch of tools for converting docbook to other formats. The > one I've been playing with is 100% Java. > > To convert docbook to (x)html, you run the source documents through > xalan with some stylesheets provided by the docbook project. To convert > docbook to pdf, you do the above (with a different stylesheet) to > produce XML-FO output, then run that through apache FOP. The publishing industry would have a good laugh here. True they use XML extensively and DocBook/XML has a place, but they all use extortionately expensive XML-FO toolchains that actually work. > Because these tools are 100% java, and relatively small (certainly > compared to the 600meg texlive distro needed for the mac), they could be > checked in to subversion. This means that there would be no setup effort > for a developer to build (and contribute to) the documentation: just > checkout and gradle userguide. Setting up the latex tools is complex and > confusing and fragile. Bad metric. The faults of Mac packaging are the faults of Mac packaging -- and its 800MB on my Mac Mini, but then I don't actually use that I use Ubuntu where you can pick and choose and so avoid the 400MB of foreign language documentation. The argument about managing the toolchain is, however, a strong one, so keep on with that. I still hate authoring material in XML, or HTML for that matter. Also Subversion should be avoided as well :-) > Having the tools in svn would also mean that the CI builds could > generate the documentation (and test the generation of the documentation > on multiple platforms). > > Having docbook integration might also be an interesting option for > report/website generation too. There is nothing you can do in XML you can't do with LaTeX and indeed vice versa. The question is what is easy and what is hard using the format for the purpose it is being used for. For writing books LaTex is best and DocBook/XML come a far distant second. > - Familiar technologies > > I think xml + xslt are technologies more familiar to java developers and > the pool of potential Gradle contributors, than latex is. This lowers > the barrier for contributing to the documentation. This is a bit sophistic. However the point about contribution is important. I would suggest that neither XML nor LaTeX are appealing in that sense. They are however the only sane representations for version control. > - Better documented > > Latex has heaps of documentation, and most of it is not very detailed. > Docbook has some fine and detailed documentation. There's the definitive > guide: > > http://docbook.org/tdg/en/html/docbook.html > > and the user guide for the stylesheets: > > http://www.sagehill.net/docbookxsl/index.html Sorry but this is just wrong. LaTeX has excellent documentation, not only online but also in physical form, i.e. books. DocBook/XML has some good documentation agreed. I think the point here is that you found the latter but not the former. > - Better looking output > > The pdf that latex produces looks dated (and not in a funky retro kind > of way, just kind of tired and old). I think the docbook generated > output looks better. Sophistry. And indeed casuistry. Just because the default LaTeX fonts are crap and the default LaTeX styling crap doesn't make the tool crap. It takes only a small amount of effort (admittedly relatively expert effort, but then this is also true of DocBook?XML) to make a LaTeX document look good -- cf. "Python for Rookies" by Sarah Mount, James Shuttleworth, and errr.... me. Typeset purely in LaTeX by errr... me. And I am not a LaTeX expert, for that you need Sebastian Rahtz or one of that crew. (http://edu.cengage.co.uk/instructors/product.aspx?isbn=1844807010 http://www.amazon.co.uk/Python-Rookies-Sarah-Mount/dp/1844807010/ go on, you know you want to buy it :-) > - More options for customisation > > Because docbook is an xml based markup, we have more options for > transformation and customisation. The docbook stylesheets have > (apparently) been designed to be easily extended to change the generated > markup. The HTML markup that they generate is semantically cleaner than > that produced by tex4ht, and so is easier to style. This is true. So what repurposing are you expecting other than PDF and HTML generation? There is no point in planning for situations that will not happen. I suspect the quality of the HTML generation is a factor of the configuration of the tools not a problem with the tools per se. Refer back to the PDF generation issue. It is not LaTeX that is the problem here it is the configuration of LaTeX for this case. > More importantly, the documentation describes how to do the > customisations, which cannot be said for the atrocious tex4ht documentation. > > I could keep going, but you get the idea. > > Thoughts? This reads like advocacy of the new convert. You will find DocBook/XML, XSLT, XML-FO has an equal number of irritations jsut as teh LaTeX toolchain has. YOu are highlighting the latter without acknowledging the former. I bet that if the change to DocBook/XML is made then down the line there will be clamour to switch to LaTeX. In the end the people doing the writing make the choice. Currently that is Hans and yourself. -- Russel. ==================================================== Dr Russel Winder Partner Concertant LLP t: +44 20 7585 2200, +44 20 7193 9203 41 Buckmaster Road, f: +44 8700 516 084 London SW11 1EN, UK. m: +44 7770 465 077
signature.asc
Description: This is a digitally signed message part
