Documentation markup experience

[Jim Campbell]

Hi All,

On Wed, Jun 16, 2010 at 7:22 AM, Daniel Holbach
<daniel.holbach at ubuntu.com>wrote:

> On 07.06.2010 16:36, Jim Campbell wrote:
> > I agree with much of what Milo has written, and just wanted to add a few
> > things.  With regards to writing in Mallard, there is a GSoC student
> > working on an online Mallard editor this summer.  This could simplify
> > the Mallard authoring process even further, but we'll have to see how
> > things turn out on that project.
> >
> > As for PDF output, Milo mentioned that there is no PDF option for
> > Mallard at the present time, but even if there were . . . FOP only
> > provides for relatively basic PDF formatting.   This affects DocBook PDF
> > output, too.  LaTeX provides for excellent PDF output, but it suffers
> > with regards to ease of translation.  AFAIK, there are no automated
> > tools in place to process LaTeX docs, as they are not XML-based.
> >
> > Mallard docs can reasonably be put into a format resembling a book.  You
> > can see an initial draft example of this at the Gitorious page for the
> > Snake Wrangling for Kids book.  http://gitorious.org/swfk
>
> Thanks a lot for all these comments. If there's any more comments, let
> me know.
>
> Have a great day,
>  Daniel
>

Daniel, did you get a chance to look at the Snake Wrangling for Kids draft
book?  If not, please clone that gitorious repo and take a look at chapter
1.

The content and style/appearance of that chapter is a bit rough, but it
would give you an idea of the Mallard-based output.  Also keep in mind that
(as Milo said) this is kind of a funny way of using Mallard.  SWFK is using
Mallard to write a book, while Mallard is more built to be more
topic-focused.

One of your original criteria was to have PDF output available, and for that
reason I'm leaning toward DocBook for the project.  When dealing with
packaging tasks and concepts, I think it would be helpful for folks to at
least have an option to output to PDF, and DocBook provides this.

I'm not a packager, and am interested in packaging, so I think I would be a
good person to work on these docs.  I've been sketching out some ideas,
which you can grab from Launchpad: bzr branch
lp:~jwcampbell/+junk/packaging-guide


These are just notes, but I think you can see the general direction that I
think the project could go - Laying out some big-picture information about
packaging for Ubuntu, identifying some prerequisites, and then letting the
person choose from a list of specific packaging tasks.

I think that converting the packaging docs would be a worthwhile effort, but
I'd need some help.  Who would be interested in assisting on this project?

Please also feel free to share any feedback on what I've written above.
Does DocBook sound pretty reasonable to folks for now?

Jim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20100622/79ae8908/attachment.html>