Page MenuHomePhabricator

An extension to edit a DocBook documentation on MediaWiki
Open, LowPublic

Description

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.


Version: unspecified
Severity: enhancement

Details

Reference
bz61047

Event Timeline

bzimport raised the priority of this task from to Low.Nov 22 2014, 3:07 AM
bzimport set Reference to bz61047.
bzimport added a subscriber: Unknown Object (MLST).

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.

Wikimedia will apply to Google Summer of Code and Outreachy on Tuesday, February 17. If you want this task to become a featured project idea, please follow these instructions.

Qgil added a subscriber: Spage.

@Spage, do you think this project fits in our current Documentation efforts?

@Spage, do you think this project fits in our current Documentation efforts?

No. To my knowledge no MediaWiki or Wikimedia project has documentation in DocBook format. (Still, this is a neat project.)

Ok, I'll move this out of the current round for now.

I want to participate in upcoming outreachy round. I want to know more about the project and interested in working on this project during outreachy internship.

I want to know more about the project

Hi @Adishaporwal, thanks for your interest! If you have specific questions related to fixing this task, please ask them! If you have general questions about Outreachy, please refer to the Outreachy discussion page. Thanks!

I have following queries:

  1. I want to know more about the skills required for the project?
  2. How the project will implement?
  3. What are the first steps I should take to understand the project in details?

Dereckson might be able to elaborate, but let me provide some pointers:

  1. How the project will implement?

Via a MediaWiki extension. https://www.mediawiki.org/wiki/How_to_become_a_MediaWiki_hacker has a section called "Working on extensions".

  1. What are the first steps I should take to understand the project in details?

For some general steps and how to get started, please check https://www.mediawiki.org/wiki/How_to_become_a_MediaWiki_hacker and https://www.mediawiki.org/wiki/Developer_hub

This is a message posted to all tasks under "Re-check in September 2015" at Possible-Tech-Projects. Outreachy-Round-11 is around the corner. If you want to propose this task as a featured project idea, we need a clear plan with community support, and two mentors willing to support it.

This is a message sent to all Possible-Tech-Projects. The new round of Wikimedia Individual Engagement Grants is open until 29 Sep. For the first time, technical projects are within scope, thanks to the feedback received at Wikimania 2015, before, and after (T105414). If someone is interested in obtaining funds to push this task, this might be a good way.

I would love to apply to this task as a Possible-Tech-Projects for the Outreachy-Round-11 internship. Can I or should I create a project proposal for this task?

Would someone be available to mentor this project? @Dereckson: Do you know?

Looking at the discussion above between Nemo and Dereckson, I think the are still some open questions. Maybe this is not a good candidate for this round yet, unless potential mentors join quickly and agree on the scope of the project.

As @Nemo_bis remarked,

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.

If it's just storing DocBook files on wiki and then having source editing of them, the extension would

  • add a new content type/content model
  • use the CodeEditor extension when editing the file (as we do for JSON editing, e.g. editing an EventLogging schema).
  • display the page's DocBook source code using the existing syntax highlighting extension. It doesn't look like Pygments supports DocBook markup, but it supports XML.
  • figure out how to page through the docbook file. The way we paginate PDF files (sample) might be relevant.

If you want to render actual DocBook pages and/or have a WYSIWYG editor, you need a much fancier content handler. There might be ways to use a different parser or Parsoid implementation; @Jdlrobson has recently experimented with alternative parsers.

Disclaimer: I'm just a a writer, and unversed in DocBook markup :-)

IMPORTANT: This is a message posted to all tasks under "Need Discussion" at Possible-Tech-Projects. Wikimedia has been accepted as a mentor organization for GSoC '16. If you want to propose this task as a featured project idea, we need a clear plan with community support, and two mentors willing to support it.