Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Post History

60%
+1 −0
Q&A What are the tool choices for producing technical documentation in PDF and web site ready HTML?

Here's what we do for that. It's not cloud-based, but it is source-control-backed, like (I hope) your code already is. Tools and technologies involved: source control DocBook DTD your favorite ...

posted 11y ago by Monica Cellio‭  ·  last activity 5y ago by System‭

Answer
#3: Attribution notice added by user avatar System‭ · 2019-12-08T03:19:13Z (about 5 years ago)
Source: https://writers.stackexchange.com/a/10051
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision by (deleted user) · 2019-12-08T03:19:13Z (about 5 years ago)
Here's what we do for that. It's not cloud-based, but it is source-control-backed, like (I hope) your code already is.

Tools and technologies involved:

- source control

- DocBook DTD

- your favorite editor for XML files (WYSIWYG possible)

- XSLTProc (with ant, but you could do make or something else instead)

- XEP (PDF generator)

- (deprecated, but I'll mention it anyway): HTMLHelp Compiler

* * *

We write our documentation source against the DocBook DTD. This is a well-established documentation standard, and while the whole spec is big, you probably only need about 20 XML elements (tags). All the usual stuff is there -- divisions (book, chapter, section, etc), formatting (emphasis, code, etc), semantics (classname, methodname, command, guielement, etc), indexing, TOC, and so on.

Alongside the DocBook XML source are stylesheets that translate your XML input into whatever output you like. DocBook comes with some of these. We feed the XML source and the stylesheets to XSLTProc to produce an intermediate output, _formatting objects_ (FO). We then have a step to transform that into PDF (using XEP), HTML (using XSLTProc), and (we don't do this part any more) a CHM file of HTML doc (using HTMLHelp Compiler).

We pack all those generation steps up into an ant build file (ant is what we use for our software builds already), but there's no reason you couldn't do it through make or whatever your build tool of choice is.

The XML source is checked into source control and collaboration is accomplished in the usual way. XML supports file inclusion, so you can modularize your books however you like. Because the docs are in our source-control system, it's easy to branch and tag them, and the automated nightly builds include documentation.

Because the source is XML, not some binary format, diff and merge work as you would expect, and you can use whatever editor you like. Some of our people use Abortext Epic (pretty high-end), some use Oxygen, some use NotePad+XML, and at least one old-fashioned person (ahem) uses emacs.

#1: Imported from external source by user avatar System‭ · 2014-01-16T20:01:33Z (almost 11 years ago)
Original score: 2