Text-file based document preparation system

Question

I am looking for a system to prepare internal technical documents that has the following basic features:

source files should be human-readable text files, so they play well with revision control
supports basic formatting (e.g. images, tables, boldface, etc.)
works with both English and Chinese characters
outputs to PDF

I could, for example, users to write HTML pages and print the pages to PDF, but this seems complicated and error-prone, and HTML is only barely "human-readable". LaTeX is also very complicated, and it has a lot of dependencies that might make it hard to process documents that are several years old.

Does anyone have any better suggestions?

Perhaps something simple like [markdown](http://en.wikipedia.org/wiki/Markdown). Tables will be tricky though. — Zoredache, Jan 06 '12 at 19:55
Here is something I found while searching for markdown: Pandoc. It can convert a number of formats including Markdown and Textile into PDF. One thing that seems lacking is control over the version of the markup and formatting engines used in preparing documents. This makes it likely that source files will need to be constantly updated to keep up with the latest version of Pandoc, which could be a major problem in the long term. — pdg137, Jan 06 '12 at 20:50

score 2 · Answer 1 · answered Jan 06 '12 at 23:41

2

Sphinx might do the trick. http://sphinx.pocoo.org/

answered Jan 06 '12 at 23:41

Sam

21
1

score 1 · Answer 2 · answered Jan 06 '12 at 20:12

1

Are you using some kind of server-side language such as PHP?

if yes you could use the FPDF Library... (http://html2fpdf.sourceforge.net/)

You basically feed it BASIC html and it will output a PDF....

answered Jan 06 '12 at 20:12

BoqBoq

111
2

Like I said, HTML seems complicated, error-prone, and hard to read. – pdg137 Jan 06 '12 at 20:25

score 0 · Answer 3 · edited Jan 07 '12 at 11:37

0

Haven't used this personally but have heard good reports from others. Quick search indicates that it supports Chinese and PDF. Very basic markup and easy to learn obviously.

http://www.methods.co.nz/asciidoc/ You've obviously investigated Latex/Tex. Have you thought about using a WYSIWYG editor such as Lyx? http://www.lyx.org/ Judging by the fact that there are also Chinese LDP translation projects, LinuxDoc and Docbook support for Chinese is also likely to be good. Toolchain for document conversion is also likely to be more mature/bug free as well.

edited Jan 07 '12 at 11:37

Tom O'Connor

27,440
10
72
148

answered Jan 06 '12 at 20:10

dtbnguyen

312
1
5

Asciidoc looks interesting! I am not looking for graphical editors, since it will be hard to combine those with non-graphical revision-tracking tools like git. I do not think linuxdoc does images, and everyone says DocBook is very complicated. – pdg137 Jan 06 '12 at 20:36
DocBook isn't difficult if you use existing templates... its just XML at its core. If you use templates all you need to do is basically insert your text in between. Plenty at, cvs.tldp.org. As for images in LinuxDoc there does seemed to have been some work on this, http://www.mail-archive.com/lyx-users@lists.lyx.org/msg24824.html – dtbnguyen Jan 06 '12 at 22:15
Lyx source is just XML, it nicely fit into any SCM (CLI or GUI) – Lazy Badger Jan 06 '12 at 22:19

score 0 · Answer 4 · answered Jan 06 '12 at 20:22

0

How about this extension to markdown (until markdown adds support for tables, etc.)

http://fletcherpenney.net/multimarkdown/features/

answered Jan 06 '12 at 20:22

Eve Freeman

228
1
2
9

1

_until markdown adds support for tables_ : I don't think this will happen any time soon. The last release of Markdown itself (version 1.0.1) was in 2004. Shop around for other projects which are based off of Markdown. – Stefan Lasiewski Jan 10 '12 at 01:52

score 0 · Answer 5 · answered Jan 07 '12 at 11:36

I think the best answer here is DocBook.
It's XML based, so the source is

a) non-binary,

b) human-readable, and

c) source control / diff-friendly.

You can use any UTF-8 characters you like, as long as you're compiling to PDF with a font that supports them (if you choose to embed an openfont).

DocBook can be "compiled" into a number of formats, including HTML, PDF, and some others too.

DocBook to PDF

DocBook Tutorial

score 0 · Answer 6 · answered Jan 10 '12 at 00:45

Here is something I found while searching for markdown: Pandoc. It can convert a number of formats including Markdown and Textile into PDF. One thing that seems lacking is control over the version of the markup and formatting engines used in preparing documents. This makes it likely that source files will need to be constantly updated to keep up with the latest version of Pandoc, which could be a major problem in the long term.

score 0 · Accepted Answer · answered Jan 10 '12 at 00:49

One possible solution is Docutils. Its "restructuredtext" format is more readable than other options, and it has built-in support for tables. The maintainers seems to be doing a good job documenting and maintaining the package, which should keep it relatively stable.

Text-file based document preparation system

7 Answers7