You are viewing a plain text version of this content. The canonical link for it is here.
Posted to c-users@xalan.apache.org by r3...@vzavenue.net on 2003/04/08 01:55:10 UTC
Suggestions for format of longer guide documentation
Hello everyone,
I've started work on a longer guide for Xalan-C++. I started using Docbook (as xml), but realized it might be nice to ask everyone what they think is a good format. I'm not very far into so it won't be a big deal if the consensus is not Docbook.
Docbook seems adequate to me because:
* xml format with xslt for transformation - seems like we should use xml tech for our documentation. :)
* extensible but has a *very* rich set of tags and styles
* fairly well distributed and used (well, at least on unix systems.)
And as I don't know of too many other xml-based documentation formats (other than html), it was kind of the first choice. :)
Any suggestions are well-appreciated, both for format or content. I can post the current outline if anyone is interested to the list or put it up on a webserver.
Thanks,
Rachael
Re: Suggestions for format of longer guide documentation
Posted by "Thomas F. O'Connell" <tf...@netcentral.com>.
I agree with the choice of an XML-based documentation format. Seems to me
that this allows transformation of the docs to other formats, anyway.
DocBook seems like a good choice to me.
Just two more cents...
-tfo
On Mon, Apr 07, 2003 at 07:55:10PM -0400, r343l@vzavenue.net wrote:
> I've started work on a longer guide for Xalan-C++. I started using Docbook (as xml), but realized it might be nice to ask everyone what they think is a good format. I'm not very far into so it won't be a big deal if the consensus is not Docbook.
>
> Docbook seems adequate to me because:
> * xml format with xslt for transformation - seems like we should use xml tech for our documentation. :)
> * extensible but has a *very* rich set of tags and styles
> * fairly well distributed and used (well, at least on unix systems.)
>
> And as I don't know of too many other xml-based documentation formats (other than html), it was kind of the first choice. :)
>
> Any suggestions are well-appreciated, both for format or content. I can post the current outline if anyone is interested to the list or put it up on a webserver.
Re: Suggestions for format of longer guide documentation
Posted by Rachael Ludwick <r3...@vzavenue.net>.
<snip>
> Having said that - it might not be the best for doing the overall
> guide/documentation. I suppose it depends on how big things are going
> to get. So it may be more appropriate to do a programming guide in
> Docbook and the web site in Forrest?
Fairly big. I'll drop the outline on the lists when I go back over to linux.
Are you thinking the regular online website docs (Getting Started, FAQ, etc)
should be made using Forrest?
Rachael
Re: Suggestions for format of longer guide documentation
Posted by Rachael Ludwick <r3...@vzavenue.net>.
> Can the guide actually be put into CVS with the other Xalan-C++ work? It
> would let others add more easily, maybe.
> Galen
>
Yes. Right now I have it has Docbook with the major sections included as
entities (quickly realized I didn't want one monolithic file). The
subsections in could probably be done the same way, although I've only got
part of the introduction done. :)
Rachael
Re: Suggestions for format of longer guide documentation
Posted by Galen S Swint <zo...@cc.gatech.edu>.
Can the guide actually be put into CVS with the other Xalan-C++ work? It
would let others add more easily, maybe.
Galen
-------------------------------------
Galen S. Swint
swintgs@acm.org
http://www.prism.gatech.edu/~gte213x
On Tue, 8 Apr 2003, Berin Lautenbach wrote:
> Rachel,
>
> Might be worth checking out the Apache forrest sub-project, which is
> what most of the xml.apache.org sub-projects are now building their web
> sites with. There is a general level of encouragement for everyone to
> move to this format.
>
> It's a fairly simple system to quickly build a web site in.
>
> Having said that - it might not be the best for doing the overall
> guide/documentation. I suppose it depends on how big things are going
> to get. So it may be more appropriate to do a programming guide in
> Docbook and the web site in Forrest?
>
> Cheers,
> Berin
>
> r343l@vzavenue.net wrote:
> > Hello everyone,
> >
> > I've started work on a longer guide for Xalan-C++. I started using Docbook (as xml), but realized it might be nice to ask everyone what they think is a good format. I'm not very far into so it won't be a big deal if the consensus is not Docbook.
> >
> > Docbook seems adequate to me because:
> > * xml format with xslt for transformation - seems like we should use xml tech for our documentation. :)
> > * extensible but has a *very* rich set of tags and styles
> > * fairly well distributed and used (well, at least on unix systems.)
> >
> > And as I don't know of too many other xml-based documentation formats (other than html), it was kind of the first choice. :)
> >
> > Any suggestions are well-appreciated, both for format or content. I can post the current outline if anyone is interested to the list or put it up on a webserver.
> >
> > Thanks,
> > Rachael
> >
>
>
Re: Suggestions for format of longer guide documentation
Posted by Berin Lautenbach <be...@ozemail.com.au>.
Rachel,
Might be worth checking out the Apache forrest sub-project, which is
what most of the xml.apache.org sub-projects are now building their web
sites with. There is a general level of encouragement for everyone to
move to this format.
It's a fairly simple system to quickly build a web site in.
Having said that - it might not be the best for doing the overall
guide/documentation. I suppose it depends on how big things are going
to get. So it may be more appropriate to do a programming guide in
Docbook and the web site in Forrest?
Cheers,
Berin
r343l@vzavenue.net wrote:
> Hello everyone,
>
> I've started work on a longer guide for Xalan-C++. I started using Docbook (as xml), but realized it might be nice to ask everyone what they think is a good format. I'm not very far into so it won't be a big deal if the consensus is not Docbook.
>
> Docbook seems adequate to me because:
> * xml format with xslt for transformation - seems like we should use xml tech for our documentation. :)
> * extensible but has a *very* rich set of tags and styles
> * fairly well distributed and used (well, at least on unix systems.)
>
> And as I don't know of too many other xml-based documentation formats (other than html), it was kind of the first choice. :)
>
> Any suggestions are well-appreciated, both for format or content. I can post the current outline if anyone is interested to the list or put it up on a webserver.
>
> Thanks,
> Rachael
>