⚠️ ** Fallback** ⚠️ 🗂️ Page Index for this GitHub Wiki The presentation-oriented QuickBook is converted to "semantic" BoostBook, which in turn is converted to (presentation) HTML and PDF.ĭocBook might help get us to a world in which all the documentation on your open-source operating system is one rich, searchable, cross-indexed and hyperlinked database.Įven if you believe this, for now it might be better to focus on documentation itself, and if your resources are limited, it is better to keep your markup simple. Obviously, the former dominates, but having more of the semantics is rarely worth the hassle.ĭevelopers of Boost libraries use BoostBook (extended DocBook) as a documentation format.īoostBook docs are not easier to maintain than DocBook docs, so some of the developers use a light-weight markup language named QuickBook. Like all popular markup languages, DocBook contains both structural (semantic) and presentation information. Here is the same SimpleList rendered horizontally with In DocBook the tree of elements is explicit That's like the difference between HTML tags and. The ESR's HOWTO calls DocBook a structural markup, as opposed to presentation markup. The tools you are using may not understand it. It is possible to extend DocBook on your own, but it takes time and the extended DocBook is actually not DocBook anymore. Browsing the list of all elements takes a lot of time and although every new DocBook version comes with even more elements, it will never have all that you need. The tag craziness is what drives DocBook. (GNOME folks are designing own XML format for documentation.) Not a specific element for your needs, but then that feelsĭirty because there are very specific elements for other To mark up? Or you have to use systemitem because there's Maybe five that sort of closely match what you're trying Hunt through 50 or so inline elements, and then there are Let's quote an email from gnome-doc-list: Nor (''function or subroutine, as in a programming language''). The commands of this mini-language are neither a (which is used for executable program) 417 elementsĭocBook has hundreds of tags (elements), mostly very specific tags, but often none of them is appropriate. I feel bad that he had to read between the ugly tags and that the markup wasted also his time. He corrected my English and rewrote parts of the text.
FITYK CALL METHOD FROM TEXT FILE MANUAL
In my experience, the most painful thing in writing DocBook is embedding mathematical formulas and figures,Īnd trying to make it look decently in both HTML and PDF.ĭuring the seven years of maintaining Fityk manual only one user bothered to edit the XML. The tags don't help with searching in any real world scenario, and probably will never do. There is a lot of tags that don't change rendering. You waste a lot of time on tagging, and the only difference it makes is that the source is uglier and harder to maintain. This makes documentation (source) hard to read and write. Two representative examples from DocBook docs (fromĬan be set to 7, 11, or 15. Why I do not like DocBook heavy weightĭocBook is a heavy-weight markup language. Although I like more the syntax of Markdown, reST is extensibleĪnd, thanks to Sphinx, it is easy to generate good looking HTML and PDF.įinally I converted the manual to reStructuredText and, after a few months, I can see this was a good move.
I use it to generate docs from code, but it's not so useful for stand-alone manual. Intended to be used by children, but the idea was abandoned.
One guy working for OLPC wrote a draft of CrossMark,Īn extensible markup language based on Markdown,.I really hope they succeed, but like Markdown, it's not really suitable ''to be used across different wikis'' called Creole. There is an effort to create an universal, unified markup language.In the zoo of wiki and forum markups, Markdown is an elegentĪnd popular one, but rather limited and not extensible.In 2009 I considered a few lightweight alternatives: I maintained the manual (20-30 pages) in DocBook format for 7 years.ĭocBook was a pain to write, read and process (especially math and figures). I started using DocBook for the Fityk manual in 2002, after reading ESR's DocBook Demystification HOWTO.ĪFAIR in that time the major alternatives were LaTeX, GNU Texinfo and HTML.
0 kommentar(er)
