Re: [xmlroff] Introduction

[Tony G. <Ton...@Su...>]

Matthew Mackey <mm...@ma...> wrote at Tue, 23 Mar 2004 11:18:42 -0800:
> I'm new to the list, so I'm doing a little introduction. My name is 
> Matthew Mackey - everyone calls me Matt - and I'm here to lend what 
> help I can to the project. My skill set is mildly eclectic, having a 
> good C/C++ and Java foundation with a variety of database and 
> multimedia stuff thrown in.

Welcome (again).

> Tony already sent me some ideas about things that could use attention. 
> I figure since I like to really get my head around something before I 
> dive in, time I spend getting to know the project would be good for 
> enhancing the documentation, something that Tony mentioned needs doing.
> 
> So one of my first questions would be about what format(s) should the 
> documentation be in. I believe (correct me if I'm wrong) I saw javadoc 
> style comments/markup in some of the files in my initial glance. So 
> that would be one area to continue expanding. But I'm assuming that 

Get to know gtk-doc.  Assuming you have gtk-doc on your system, adding
--enable-gtk-doc to the configure command line will enable building
the documentation when you run 'make'.

In addition to the Javadoc-like comments that you can put in the
source code, there's a .sgml file for each source code module in
docs/tmpl to which you can add additional stuff (using DocBook markup)
that will end up in the generated HTML documentation.

> there's a desire for external documentation as well. Perhaps a primer 
> of some sort that would cover internal structure for xmlroff developers 
> and/or proper usage for those trying to use it in a solution? Should it 
> be html? Raw text? (Or even XML and XSL sheets so we can make PDFs of 
> it with xmlroff! Okay, I'm getting ahead of myself...)
> 
> I'm open to ideas...

xmlroff.fo in the source distribution is a simple man page for the
xmlroff executable in FO markup that serves the dual purposes of man
page and being something that you can use to check that xmlroff works.

The short-term place for documentation until it's cooked enough to
bake into the gtk-doc documentation is meant to be the xmlroff Wiki at
http://www.xmlroff.org/phpwiki/.  If what you want to write doesn't
slot in to the structure of the current Wiki pages, then just add
another top-level Wiki page.

Regards,


Tony Graham
------------------------------------------------------------------------
Web Products, Technologies and Standards           Phone: +353 1 8199708
Sun Microsystems                                              x(70)19708
East Point Business Park, Dublin 3, Ireland