Semantic docs - DocBook vs. Sphinx


#21

Going from wiki markup to something like ReST is what is called up-translation. That is, going from a less precise or less rich format to a more precise/rich format. Such transformations are problematic because at best, they will not take full advantage of the richer format and at worst they may not be compatible with the constraints of that format. It is in the latter case that transformations can make a mess.

However, not all transformations between markup languages make a mess. Going from a richer or more precise format to a less rich/precise format should be reliable. For instance, going from ReST to HTML, which is what the Sphinx publishing engine does, should be entirely reliable.

This is very much the point of creating semantically precise markup languages that express specific constraints or contain structures appropriate to certain subject matter, they allow you to constrain the writing process to improve quality and consistency while supporting reliable algorithmic publishing.

I agree that Renato’s proposed tool chain is not a good one, and that it is likely to create a mess. I just wanted to caveat the assertion that automatic transformations usually make a mess. Without automatic transformations, markup-based writing and publishing would not be possible. It is all about creating or selecting a format that can be reliably transformed into the outputs you want. This is why semantically stricter formats are usually to be preferred.


#22

Thanks for a great clarification, Mark, well put.


#23

can someone explain me what does it mean “semanthc” ?
I’m not sure (or maybe yes) what could be this big difference.

TIA

Renato


#24

Practically, this often comes down to having specific markup for concepts in your target-field. If you’re, for instance, writing about a computer system you might end up having specific markup for filenames, paths, buttons, key-strokes.

In Sphinx you can, for instance, describe a filepath inside a paragraph like this:

You can find the configuration in :file:`/etc/myapp/main.cfg`.

This allows a renderer or search engine to treat such statements differently from, let’s say, simply italic text.