XML for Documentation - Standards?

Question

I need to create Documentation for a tool (Manually written User Documentation, no Developer/API Documentation from the Source Files). Now, there are about a billion different ways to do it, but I have the following requirements:

• Needs to be a physical file, so that it can go to SVN
• Needs to be printable
• Needs to be readable and searchable from the Web
• Needs to be able to include Images and basic formatting (Headlines)
• Optional: Needs to support Inline Links (Table of Content => Heading)

Word or PDF documents fulfill most parameters, but are not really readable from the web. A Web-based solution is not really printable.

So my idea is to have one central file that only includes Content, and then some tool that can generate output in PDF and additionally in HTML.

Now, LaTeX comes into mind, but this is a bit overkill. I thought of maybe some XML and then XSLT processing? The reason for wanting XSLT is also because then I can use the XML Viewer Web Part within Sharepoint to display it.

As I do not have much experience and don't want to reinvent the wheel, I just wonder if there is already some sort of "standard" XML Schema for Documents and standard XSLT? and as bonus, a PDF conversion?

I know I can just build that myself, but maybe one of the eleventy billion XML Standards specifies a "Documentation XML Schema" already?

Answer 1

html? (.chm if you want)

Answer 2

What programming language you're using? In case of .NET there are tools (such as sandcastle) that transform the XML documentation created by visual studio. If you're using java I think there are great tools that do the same (Doxygen).

Most of those tools create chm as well as html web site of your documentation.

Answer 3

docbook is probably what you want.

Answer 4

Fop will let you go from xml to pdf with a bit of work

http://xmlgraphics.apache.org/fop/

an example of using fop given here http://alistapart.com/articles/usingxml/ Look for the "Conversion to Print" section.

To me HTML feels like a better solution, how complex is the layout of these things?

You can use CSS to style specifically for printing not just screen display.

Answer 5

DITA can generate different kinds of output and is written in XML. There's also an Eclipse plugin for it.