Loading...
 

DocBookDev

All materials on this page is just a draft. No actual work is done by the moment I'm writing this or this work can't be used as described here. It is made with a glipse into the future so any who would like to contribute can design the most of these ideas.

What is DocBook for Developer

DocBook is intermediate XML format, very convenient for converting information into presentation shape. It's raw XML structure (though well documented) and popularity allows various templates to be applied easily to the same text. General DocBook templates don't pay attention on which kind of text contained within particular XML DocBook file. Rules apply whenever document must an article or a book.

DocBook and Wiki

It was not the one man thinking DocBook will be a good Wiki feature.

Editing pages with Wiki tags is much more convenient, than in XML, but for conversion to various formats (i.e PDF, TXT, CHM) DocBook is more suitable, because you may use different templates and styles invented by authors who may even not to know anything about wiki. Needless to say, that conversion from DocBook isn't limited to just PDF. So there must be a way to dump wiki structure to DocBook, which you can use further to get your own stylish hard or softcopy of your wiki.

This idea to be able to convert wiki pages to DocBook is especially valuable for documentation.

DocBook and Documentation

Documentation can be converted for offline browsing at any time in any suitable format like .txt, .html, .chm and so on. It is very convenient for technical writers to have incomplete offline documentation as reference, because it is MUCH faster. In many cases plain .txt format can be automatically processed for spelling mistakes and double/bad words. It crucial for production releases and commercial docs. There can be documentation autobuild system.

DocBook was used to create PHP and PEAR manuals.
http://www.php.net/manual/en/about.generate.php
http://cvs.php.net/cvs.php/phpdoc?login=2

http://www.php.net/manual/howto/index.html


Technical Details

Export Wiki to DocBook (draft)

Export to DocBook must be proceed through three steps:

  1. First user chooses option "export DocBook" from wiki page (or just Export, or Save Page..) Script analyses possible DocBook converters for this system, available extensions, templates for DocBook and...
  2. User chooses which intermediate (i.e. DocBook) or final (i.e. HTML, PDF, ... plugins?) format he/she wants, possible templates for this format (in directory templates\docbook). Templates are not those of Smarty, but XSLT or others if necessary extensions are available. Additionally User chooses if he/she want to dump one page or structure of pages in one DocBook/PDF/HTML/... .
  3. Third step is necessary if user wants to dump a bunch of pages. On this page he will see whole structure, to which this page is linked together with all backlinks and forwardlinks.

It might look like tree structure:

o Structure (Save ThisPage with...) -up one level- -show whole structure-
o - wikipageone
o - wikipagetwo
o - - out_of_structure_wiki_page
o - - back: userone
o - - back: documentation
o - wikipagethree
- - ext: http://somesite
o - - out_of_structure_wiki_page
o - wikipagefour
o - - back: another_wiki_page
o - thiswikipage
o - - wikipagetwo

where o denotes checkboxes which pages to include

Inverse: DocBook to Wiki

There must be a siple mapping from most DocBook tags to Wiki tags. It is yet to decode if this mapping must be one-to-one or many-to-one. In the first case all transformations are lossless, in second they are not.

Current Work

Search for best match for DocBook tags to Wiki tags.
Wiki code research to find the best solution how to realize this feature.

Related Links

Ruminations on DocBook V.next
More Ruminations on DocBook

Who is Working on this Matter

UserPagetechtonik

P.S. I'm (UserPagetechtonik) not an expert in DocBook and I can be wrong in some concepts, so feel free to correct any errors if you find any.


Page last modified on Sunday 07 March 2004 23:55:51 GMT-0000

Upcoming Events

1)  Thu 20 Feb 2020 14:00 GMT-0000
Roundtable Meeting 2020 02

Why Register?

Register at tiki.org and you'll be able to use the account at any *.tiki.org site, thanks to the InterTiki feature. A valid email address is required to receive site notifications and occasional newsletters. You can opt out of these items at any time.