Noah (angelbob) wrote,
Noah
angelbob

Doc tool for a book

For those who haven't been paying attention to all my geek hobbies, I've been working on a textbook for a language called LPC. For those who *do* pay attention to other people's geek hobbies: what documentation tool should I be using for writing?

Currently it's a great big blob of HTML. Separated into maybe ten separate pages, but hardly elegant, and all maintained by hand. At the very least, a tool should separate out the individual pages for me and link from the table of contents to the section and back.

I thought: "I'll check out TeX and LaTeX". One, of course, is legendarily difficult to learn. That's not what stopped me -- what stopped me is that all the tutorials are written in TeX. That's roughly like if all copies of WinZip came WinZipped, so you'd have to write your own decompressor to use the tool. No, not really that bad, but it still sucks -- particularly since it's hard to turn TeX into anything I can easily read, which is a whole *other* reason not to use it. Then there's LaTeX, which seems to have the same dearth of tutorials. I tried texinfo, and the sample program doesn't even run on my copy of RedHat 7.2 -- is the is changing so fast that a standard 4.6 sample program, just a minimal doc with one chapter, shouldn't work on 4.0? Or are the docs just screwed?

DocBook, of course, is an incredible pain to get started on and requires a large number of obscure tools (ever try to download the DocBook authoring stuff? Ugh), plus learning a weird SGML markup language specific to itself.

So so far, it looks like the best way to do this is to write a custom Perl script. That's what I did for my API docs as well, and what it looks like I'll be doing to put headers and footers on all the documents on my site.

As I slowly find myself managing an ever-larger bundle of custom Perl scripts to assemble my site from HTML bits, I have to ask... How do *other* people do this?
Subscribe
  • Post a new comment

    Error

    default userpic

    Your IP address will be recorded 

    When you submit the form an invisible reCAPTCHA check will be performed.
    You must follow the Privacy Policy and Google Terms of use.
  • 9 comments