Slashdot Mirror
Tools for Publishing in Multiple Formats?
Truist asks: "What are the best tools (windows or *nix) to use to publish a single source document in multiple formats, specifically plain text, multi-page HTML, and PDF? I'm trying to publish a (60-page+) NetBSD installation guide/documentary online, and I want plain text for easy download and 'less'-ability, HTML for easy browsing and search engine indexing, and PDF or Postscript for easy printing. It's currently a Word document (I know, I know - I'm happy to manually convert it to something else) with multiple styles, including regular text, lists, internal links, external (web url) links, code, and notes, and I'd like to preserve as much as possible of each in the final output. Some additional notes: there are no graphics, and I expect to update this document periodically, or to split it into parts and maintain the parts (think master document / subdocuments). It won't be updated too often, but if re-publishing could be scriptable, that would be fantastic."
I have seen a variation of this question at least two times posted here. The unanymous answer is usually docbook and in this case is more relevennt, since the document is technical in nature.
good pick is DocBook: The Definitive Guide written by Norma Walsh (who chairs the Oasis DocBook Technical Committee) and published by O'Reilly that. Of course the book is also available in HTML, PDF and plain text.
Come on... this has to be a planted question ;)
TeXinfo
texi2html
The subject says it all. Apparently, it's the standards-based, open-source-conforming way to do it. I've heard paeans sung to FOP but I haven't used it, yet.
Specifically latex, and more specifically pdflatex for pdf output and tex2page for html. With some hacking you should be able to script tex2page into outputting text as well.
To some extent the texinfo folks have solved this problem as well. The DocBook stuff mentioned elsewhere might be very nice but I have no experience with that.
It's highly likely that OO is scriptable.
DocBook SUCKS. However, it's probably the best thing out there for the job.
The problem with DocBook might also be considered its strength - basically it was designed by a committee, and evolved several humps. Each influential party behind it pushed the features that they wanted to see into it. Each individual feature set is a pretty good coherent package which will let you create documents just like [insert-project-name-here]'s own documentation - pretty neat! However, the different feature sets clash _horribly_, and if you pick and chose beween them you'll end up with an inside-out baboon.
(And to be honest I've not discovered _any_ feature that the various admonitions don't look out-of-place near with! Most of the list types are pretty, erm, special too.)
I've just taken on the role of producing documentation for a small OpenSource project, and I came _very_ close to regretting my choice of DocBook. However, once you've decided what coherent subset of the features you actually need, you'll probably end up with something that looks OK in all formats.
(I was using the default Debian Jade configuration, perhaps I could tweak some of the stylesheets to look less quirky.)
YAW.
Your head of state is a corrupt weasel, I hope you're happy.
The other solutions presented so far suffer w.r.t # 4 - document maintenance. After all, if someone created their document in a visually rich editor like Word, it was probably because of ease of use and they will find it easiest to maintain it there. However, two conditions must be met for the system we're discussing:
(A) It should be possible to constrain all aspects of the document, so its has a defined, machine-comprehensible structure
(B) The maintenance application must integrate with a version-control and access-control system (a nice to have - so that document-maintenance is transparent)
Regarding (A) - it seems useful to emulate an ability from the new "Pro" version of Word 2003 - custom XML schemas that constrain document content. From what I've read about it, its like the old document field macros and templates, but more powerful and using XML Schemas for validation. I'm *guessing* (not sure - can someone with OpenOffice expertise chip in?) OpenOffice could be made to do the same thing. For example - could a 'document schema' be defined that the document is *forced* to have it's title in the middle of the first page, it's index auto-generated on the second, text in a particular style, chapter and subchapter headings in other per-selected styles, a list of figures and list of tables auto-generated as Appendices 1 and 2... ?
Regarding (B) - the scriptablity of OpenOffice should support invocation of CVS/Subversion clients.
I use roff. It is a very simple document formater. The plus is that you automatically get unix style man pages for free. Use it with make to simplify your life as well.
h tm l
Here is a concrete example. I create a roff file rwlock.man as the source. Say I want a postscript doc, then I add the following to a Makefile.
rwlock.ps : rwlock.man
groff -man rwlock.man > rwlock.ps
This uses GNU troff, on other systems you might use the troff included with your system and pipe through dpost.
If I need a pdf file, that is easy from the postscript file.
rwlock.pdf : rwlock.ps
ps2pdf -dCompatibilityLevel=1.1 rwlock.ps rwlock.pdf
You can use all sorts of other options to ps2pdf just do a 'man ps2pdf' to learn more. You can install ps2pdf in the usual ways for your system, it is a common package. If you are on MacOS X 10.3 you already have pstopdf which is similar in functionality.
Say I want a plain text file of the documentation, then I add something like this to the Nakefile.
rwlock.txt : rwlock.man
nroff -man rwlock.man | col -bx > rwlock.txt
If your system includes GNU nroff, then you can use something like gtroff -man rwlock.man | grotty -buo in the command instead. Some nroff's and their 'an' macro files are a bit old fashioned and do 66 characters per line and 66 lines per page so you may have to experiment a bit on your system. Solaris nroff is a pain with respect to this while FreeBSD gets it right.
Then if you want html, GNU troff is the best way to go.
rwlock.html : rwlock.man
groff -man -Thtml rwlock.man > rwlock.html
It generates fairly lean html with some comments that is easy to follow if you ever need to look at the source.
If you have a whole bunch of files to process, then you can use suffix rules in make to simplify that job. There numerous troff, nroff, and man page HOWTOs on the web that you can read that make it a breaze to get started with roff. There shuld be standards if you want to conform to say FreeBSD or Linux man pages.
You can go here to see the results from the 'rwlock' examples from this comment:
http://www-bd.fnal.gov/controls/micro_p/rwlock.
(Slashcode may break-up that url, I did this post in text because I did not want to deal with the lameness filter for all of the make rules.)
You can do a man on any of the commands above to learn more about them. Also roff can do a whole lot more because you can have it run various other processors as it formats. In this way you can get tables, figures, pictures, references, and even primitive equations.
Once you start doing that though, man pages cannot really look right anymore on a text console and xman is a kludge so often gets this wrong. If you start getting into more sophisticated equations for example, I would recommend latex. It is straight forward to get ps and pdf out of latex and you can try an add-on such as latex2html to get html output.
Hope this helps.
Red Hat linux comes with a simple set of tools: docbook2pdf, docbook2html, docbook2rtf to help converting from docbook to other formats. It's a lot easier than directly using jade et al.