Docs structure

[Steve Howe]

Hello all,

I've lost the first messages from the group because I had not join, so I
had to open a new message tree.

I suggest that we start by making the top level docs structure, then
writing the documentation writers chapter. Once these are made,
volunteers choose what sections/chapters they want to write.

Since I'm used to DocBook, I volunteer to write the docs structure,
unless Sylvain prefers to do it himself. I plan to add dependency on
cheetah templates in order to have more advanced macro/templating
functionality; this has proven to be more easy to use and much more
flexible then using ENTITY style macros such as:

<!ENTITY cp "<productname>CherryPy</productname>">

Another point I would like to discuss is use of indentation on the XML
sources. I think indented XML is much more easier to read and debug, but
most doc authors seem to ignore this completely. Could we adopt indented
XML sources ? I want this:

<article>
<articleinfo>
<title>DocBook XSL Stylesheet Release Notes</title>
<pubdate>01 December 2004</pubdate>
<releaseinfo role="cvs">$Id: RELEASE-NOTES.xml,v 1.35 2005/02/14 08:06:28 xmldoc Exp $</releaseinfo>
<corpauthor>DocBook Open Repository Team</corpauthor>
</articleinfo>
</article>

Instead of:

<article>
<articleinfo>
<title>DocBook XSL Stylesheet Release Notes</title>
<pubdate>01 December 2004</pubdate>
<releaseinfo role="cvs">$Id: RELEASE-NOTES.xml,v 1.35 2005/02/14 08:06:28 xmldoc Exp $</releaseinfo>
<corpauthor>DocBook Open Repository Team</corpauthor>
</articleinfo>
</article>

Later, we could make a build script to generate single html, chunked
html, CHM and PDF target formats. It's not hard and I do it already for
my current documentation.

--
Best regards,
Steve mailto:ho...@carcass.dhs.org

[Robert Brewer]

> Another point I would like to discuss is use of indentation on the XML
> sources. I think indented XML is much more easier to read and debug

So make a checkin script that does the indentation for you?


Robert Brewer
System Architect
Amor Ministries
fuma...@amor.org

[Steve Howe]

Hello Robert,

Tuesday, June 7, 2005, 8:36:05 PM, you wrote:


>> Another point I would like to discuss is use of indentation on the XML
>> sources. I think indented XML is much more easier to read and debug
> So make a checkin script that does the indentation for you?

That will spoil the whole point that is facilitating the documentation
writer to debug his own work. And those scripts won't indent as smartly
as a developer would do; certain tags shouldn't be indented; others,
yes, and sometimes it depends on context.

If it was that simple as using an indentation script, I woouldn't have
made such a suggestion after all...

[Lukas Linhart]

Hi steve,

E-mail Steve Howe ze dne Wed 8. of June 2005 03:02:

> If it was that simple as using an indentation script, I woouldn't have
> made such a suggestion after all...

Yes, but "smart indentation" means that no "xml-hiding" tool as xxe will not
be possible to use. No big deal, but could be little harder for beginning to
people not used to docbook.

--

Lukas "Almad" Linhart

[:: http://www.Include.cz/ ::]
[:: Including Your wishes ::]
[:: PGP/GNUPg key: http://download.almad.net/pubkey.asc ::]

[Sylvain Hellegouarch]

Hi Steve,

Selon Steve Howe <ho...@carcass.dhs.org>:

> I suggest that we start by making the top level docs structure, then
> writing the documentation writers chapter. Once these are made,
> volunteers choose what sections/chapters they want to write.

Good idea though we will need to define what "volunteers" mean exactly in that
case. Documentation is as important as the source code itself, and since we
want comprehensive and up-to-date documentation, we need a small bunch of
people knowing their stuff. As Remi said it would those people working more but
in the end we will have a decent documentation.

> Since I'm used to DocBook, I volunteer to write the docs structure,
> unless Sylvain prefers to do it himself.

Go ahead, we'll review it together anyway before checking in it.

> I plan to add dependency on
> cheetah templates in order to have more advanced macro/templating
> functionality; this has proven to be more easy to use and much more
> flexible then using ENTITY style macros such as:
>
> <!ENTITY cp "<productname>CherryPy</productname>">

Nice feature indeed.

>
> Another point I would like to discuss is use of indentation on the XML
> sources. I think indented XML is much more easier to read and debug, but
> most doc authors seem to ignore this completely. Could we adopt indented
> XML sources ?

I totally second that. But isn't it a default in most XML editor? Even emacs can
do it :)

> Later, we could make a build script to generate single html, chunked
> html, CHM and PDF target formats. It's not hard and I do it already for
> my current documentation.

Great.

- Sylvain

----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.

[Remi Delon]

>>I suggest that we start by making the top level docs structure, then
>>writing the documentation writers chapter. Once these are made,
>>volunteers choose what sections/chapters they want to write.
>
> Good idea though we will need to define what "volunteers" mean exactly in that
> case. Documentation is as important as the source code itself, and since we
> want comprehensive and up-to-date documentation, we need a small bunch of
> people knowing their stuff. As Remi said it would those people working more but
> in the end we will have a decent documentation.

I agree with the top level docs structure to start with and yes, I'd
rather have less people contribute to the documentation if it means
better quality.

>>I plan to add dependency on
>>cheetah templates in order to have more advanced macro/templating
>>functionality; this has proven to be more easy to use and much more
>>flexible then using ENTITY style macros such as:
>>
>><!ENTITY cp "<productname>CherryPy</productname>">
>
> Nice feature indeed.
>
>>Another point I would like to discuss is use of indentation on the XML
>>sources. I think indented XML is much more easier to read and debug, but
>>most doc authors seem to ignore this completely. Could we adopt indented
>>XML sources ?

Of course ... It didn't even cross my mind to not indent it :-)

>>Later, we could make a build script to generate single html, chunked
>>html, CHM and PDF target formats. It's not hard and I do it already for
>>my current documentation.
>
> Great.

Sounds good.

I can setup this script to run daily on the cherrypy.org machine so that
we always have uptodate documentation on the website, for all versions
of CherryPy.


Remi.