Take the 2-minute tour ×
Server Fault is a question and answer site for professional system and network administrators. It's 100% free, no registration required.

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

  1. source files should be human-readable text files, so they play well with revision control
  2. supports basic formatting (e.g. images, tables, boldface, etc.)
  3. works with both English and Chinese characters
  4. 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?

share|improve this question
2  
Perhaps something simple like markdown. Tables will be tricky though. –  Zoredache Jan 6 '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 6 '12 at 20:50

7 Answers 7

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

share|improve this answer

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....

share|improve this answer
    
Like I said, HTML seems complicated, error-prone, and hard to read. –  pdg137 Jan 6 '12 at 20:25

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

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

share|improve this answer
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 1:52

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

share|improve this answer

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.

share|improve this answer
    
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 6 '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, mail-archive.com/lyx-users@lists.lyx.org/msg24824.html –  user1125087 Jan 6 '12 at 22:15
    
Lyx source is just XML, it nicely fit into any SCM (CLI or GUI) –  Lazy Badger Jan 6 '12 at 22:19

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.

share|improve this answer
up vote 0 down vote accepted

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.