> Basically i will have documntation for which i want :
> - control over edits ( e.g. cvs )
> - ability to output in many formats (odt, doc, pdf, html, etc)
> - editable from linux and windows (perhaps more)
We use docbook (xml version) with subversion for revision control.
The process looks something like:
- Users check out documentation repository (you can use tortoise svn
- Edit documentation in editor of choice
- If windows, upload changes for parsing
- If Linux, install the company-specific docs toolkit and parse locally
- Run custom make file which calls saxon to create html from the xml,
pdfs from the html, publishes the html to the documentation site and
mails the docs group.
- Check validated, correct docbook xml in.
>> Currently the potential issues I see are :
> - having an index/toc, perhaps with 'links' to the sections described
> in docbook and where appropriate in the output format.
Docbook can do this automatically. Read up on the stylesheets to
determine how you'd like this handled. It will also do all your intra
and inter document linking.
> - keeping it cvs 'friendly'. Ie will various editors mangle the docbook
> xml different ways that makes the cvs log/history useless ? I can write
> a wee parser-app to pretty-print the xml, but if it's bloated with extra
> tags as per some html that may well be pointless.
>I haven't come across this as an insurmountable issue but then everyone
seems to have a similar style. Other issues I have encountered which
- There is a learning curve to write proper docbook xml.
- People *still* focus too much on what they want things to look like
and don't pay attention to appropriate markup options.
- People confuse the version control systems for the xml files with the
document publishing systems.
- It becomes increasingly slow to render the docs tree, the more
documentation gets added. On the original machine we installed it,
documentation docs suggested you go get a cup of coffee while it parsed.
I suppose if you had the time to put into it you could restrict tags
accepted by your parser, basically customising your own simplified
docbook to reduce some of these risks.
Maintained by the ILUG website team. The aim of Linux.ie is to
support and help commercial and private users of Linux in Ireland. You can
display ILUG news in your own webpages, read backend
information to find out how. Networking services kindly provided by HEAnet, server kindly donated by
Dell. Linux is a trademark of Linus Torvalds,
used with permission. No penguins were harmed in the production or maintenance
of this highly praised website. Looking for the
Indian Linux Users' Group? Try here. If you've read all this and aren't a lawyer: you should be!