Last modified: 2014-11-11 16:05:29 UTC
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 commands. 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.
Are you willing to mentor this as a GSoC project? If so, please list it at https://www.mediawiki.org/wiki/Mentorship_programs/Possible_projects
* Doesn't this depend on bug 15071/BookManager extension? * How does it relate to the DocBook export (Extension:XML Bridge used by Collection extension)? * Is the DocBook format going to be consumable by book export features à la Collection extension? DocBook is the highest-energy-level format from which any other format can be derived. It's quite a waste if you don't actually exploit it, and it's generally just a mess if you convert other formats into DocBook. * If the aim is translation, are you aware you could just add DocBook to Translate's formats? https://www.mediawiki.org/wiki/Help:Extension:Translate/File_format_support
(In reply to Nemo from comment #2) > * Doesn't this depend on bug 15071/BookManager extension? If BookManager is released, it could be a nice addition to the solutions covered by this bug. > * How does it relate to the DocBook export (Extension:XML Bridge used by > Collection extension)? It could be a approach, not my favorite. Please note we don't have used XML bridge to solve our problem "HTML 5 <--> wiki code". > * Is the DocBook format going to be consumable by book export features à la > Collection extension? DocBook is the highest-energy-level format from which > any other format can be derived. It's quite a waste if you don't actually > exploit it, and it's generally just a mess if you convert other formats into > DocBook. If we want a goal "Use MediaWiki as a comfortable DocBook editor", there is a need to transparently support import and export. Better, in a continuous integration, to be able to immediately launch the DocBook regeneration. The more elegant, more costly as effort approach to achieve this goal would be a Parsoid DocBook <--> wiki code. This is not as costly as to reproduce all the Parsoid effort: Parsoid offers a tokens representation. This representation is an intermediate, clear and logic format of the data. The work to do is so the Tokens representation <--> DocBook, which could reuse a lot of XML DOM tree generation components of the Tokens representation <--> HTML 5 current part. As you highlighted, to loss DocBook functionality would be a pity, as DocBook offers to the document publishing ecosystem us a lot of existing workflows. > * If the aim is translation, are you aware you could just add DocBook to > Translate's formats? The main aim is to offer a comprehensive authoring environment to produce a documentation. That includes tasks like editing, authoring, reviewing, structuring before translating. Please note most projects primarily maintain en English translation, which is then a base for more or less up-to-date translations. A secondary goal is to use MediaWiki to write a comprehensive and collaborative book, to get the benefit of rich history and discussion capabilities. Translation is another secondary goal. And an important one for some projects with a willingness to be universal. The Linux from scratch French documentation team for example selected recently gettext to help translators to deal with DocBook complicated format (their judgement, not mine or an objective one). Please note the bug description text isn't updated: as a transcript of a text written in 2012, it doesn't take in account Translate extension state of art. I write this comment at the end of the Bugzilla era, where descriptions aren't editable, that will wait Phabricator migration. Of course modern implementation of the translation part has to use Translate extension for a better product coherence. So, in a nutshell, DocBook support by Translate extension is useful and will largely solve the translate need. Yet, before to translate a text, we need to write this text.
(In reply to Dereckson from comment #3) > If BookManager is released, it could be a nice addition to the solutions > covered by this bug. Requirements 2–4 appear to need MediaWiki to know the concept of multiple pages which make a single thing (a book). Either you trim the requirements down, or the functionality greatly overlaps with book manager. It's not clear from your goals in comment 3 what makes those requirements required. > It could be a approach, not my favorite. Please note we don't have used XML > bridge to solve our problem "HTML 5 <--> wiki code". What's the relationship? > If we want a goal "Use MediaWiki as a comfortable DocBook editor", there is > a need to transparently support import and export. Import and export from and to what formats? Can this need be satisfied by keeping the entire book in a single page? > Better, in a continuous > integration, to be able to immediately launch the DocBook regeneration. > > The more elegant, more costly as effort approach to achieve this goal would > be a Parsoid DocBook <--> wiki code. Unless there are libraries to convert from DocBook to HTML5 and back, this sounds like a very bad idea. (I doubt such a thing may exist.) I don't understand if you're trying to say this bug is also/mainly about making a WYSIWYG editor for DocBook; in that case, it would be useful to say it clearly. At any rate, it's important to look at what publishers with experience in using DocBook as their master format are doing. The most developed example in Italy (and EU?) is Il Mulino; AFAICS, they always keep DocBook as their underlying format (because you can get perfect PDF, ePUB and any future format from it) and then have some HTML5 on top of it. Some research is needed. * http://www.smartbook-tisp.eu/business_cases/pandoracampus * http://www.slideshare.net/TISP/andrea-angiolini-il-mulino-about-pandoracampus-frankfurt-book-fair-2014-tisp-workshop * http://tropicodellibro.it/notizie/pandoracampus/
