Web browser: ---
            Bug ID: 61047
           Summary: An extension to edit a DocBook documentation on
           Product: MediaWiki extensions
           Version: unspecified
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: Unprioritized
         Component: [other]
    Classification: Unclassified
   Mobile Platform: ---

Major open source projects use DocBook as documentation format: FreeBSD, PHP,
OpenStack, MongoDB for example.

This is also a format used by publishers like O'Reilly.

Currently, to edit such an open source project documentation, the workflow is:
1. checkout the documentation portion of the project repository with the
documentation source (CVS, SVN) or clone the documentation repository (Git,
Mercurial, etc.)
2. edit it, which requires a litte knowledge of the DocBook markup, and of the
project conventions (like <emphasis role="strong">Lorem ipsum</emphasis> for
'''Lorem ipsum''')
3. send a pull request, a commit in the code review system, or get a diff and
send it as a patch

Some projects wrote an online editor for this documentation, but nothing very
universal or ergonomic.

Let's note it's overkill to fix a typo.

On the other hand, MediaWiki allows a workflow easy to edit the documentation.
For trivial changes or to write new full pages.

An extension to edit the documentation would have the following features:
(1) import a DocBook documentation to a wiki documentation namespace (that
could be main or another one)
(2) import a DocBook documentation to a wiki documentation namespace, as
subpages from a named page
(3) export a page, a full namespace or subpages to a DocBook document
(4) offer an option to trigger build process (two are mainly used in the
DocBook world to produce documentations outputs, one in pure XSLT, the second
more complex based on Ant)
(5) in a second phase, add support for translation

A same wiki could contains more than one DocBook document.

For (4), the easiest implementation is to add an hook triggered as runtime when
a page related to the documentation is modified and let the user who want that
to create a function/an extension for its build process ; the more elaborated
implementation is to offer to trigger the most standard DocBook rebuild

For (5), I advice /fr /de /ar to use subpages, it's a lot clearer to use than
the interface translation system, and the goal of this extension is to allow
anyone to edit documentation, without to have to learn anything more
complicated than how to use the visual editor or to write in wiki code.

You are receiving this mail because:
You are the assignee for the bug.
You are on the CC list for the bug.
Wikibugs-l mailing list

Reply via email to