ubuntu-manual team mailing list archive

[Ilya Haykinson <haykinson@xxxxxxxxx>]

>
> Seems like DocBook has the most flexibility, but since there is some
> barrier to entry when writing DocBook maybe it'd be worth the time to come
> up with some kind of simple editing tool.  That is if there isn't something
> out there better than Gedit :-).
>

My hope is that we have two classes of contributors:

 1. The general public (the community)
 2. The experts (ubuntu-doc people, ubuntu-manual people etc)

For the general public, I would propose that we support a plain text input
method -- no markup whatsoever.

For the experts, we can expect them to learn how to author DocBook or any
other format.

And, to bridge the complexity gap for the experts, we can offer a simple
plain-text-to-DocBook converter which can take a quick stab at doing some
basic markup (i.e. recognize step lists and convert those to DocBook, mark
up paragraphs, etc) to simplify the amount of work required to fully mark up
the submitted copy. Think of this as a sort of a mini
markdown/textile/reStructuredText etc to help simplify authoring, but not
really replace final markup work.

This can be in place comparatively quickly, and in the future we can decide
whether there are resources or not to work on better editing/authoring
tools.


> Can you elaborate more on what metadata you're looking to store?
>>
>
Well, as a simple example, human-readable section and content unit
(paragraph?) titles; the mapping of content units to the combined "works";
the license information, etc, etc.


> In my very humble opinion, using an RCS for is much preferable to straight
> database. From working on the Server Guide content for a while now, having
> the ability to roll back changes and see diffs between files is very
> necessary.
>
> The hybrid approach may make sense though.  If you could store information
> about a commit based on revision number... there's probably some type of bzr
> hook that could add entries to a database.
>

Yeah, I think the hybrid approach could work pretty well. It'll require
interacting with bazaar, which fortunately is very easy with bzrlib in
Python, as an example.

-ilya