You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by James Dodd <jd...@accucard.com> on 2004/01/26 13:46:11 UTC
Doco - useful for Apache documentation project?
Hey,
Just wondering whether 'Doco' may be of any use to the Apache
documentation project.
It's a lightweight markup syntax for converting text to HTML docs,
and has lots of useful & powerful features.
Documentation is at
http://doco.sourceforge.net/
And it can be downloaded from
http://sourceforge.net/projects/doco
Cheers,
James
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Doco - useful for Apache documentation project?
Posted by Erik Abele <er...@codefaktor.de>.
On 26.01.2004, at 14:35, Mads Toftum wrote:
> On Mon, Jan 26, 2004 at 02:06:06PM +0100, André Malo wrote:
> [SNIP lots of good points]
>>
>> all IMHO, of course.
>>
> agreed - that's roughly my conclusion after looking at Doco.
> There's no sense in undoing all the hard work that has
> already been done.
Yep, same here. I did also take a look at Doco and have to say that it
might be nice in some cases but due to the facts mentioned by André it
won't be sufficient for the Apache documentation.
Cheers,
Erik
Re: Doco - useful for Apache documentation project?
Posted by Mads Toftum <ma...@toftum.dk>.
On Mon, Jan 26, 2004 at 02:06:06PM +0100, André Malo wrote:
[SNIP lots of good points]
>
> all IMHO, of course.
>
agreed - that's roughly my conclusion after looking at Doco.
There's no sense in undoing all the hard work that has
already been done.
vh
Mads Toftum
--
`Darn it, who spiked my coffee with water?!' - lwall
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Doco - useful for Apache documentation project?
Posted by André Malo <nd...@perlig.de>.
* James Dodd <jd...@accucard.com> wrote:
> > * I18N and charset issues are (basically) not a problem. I'm certain,
> > doco has e.g. problems recoding iso-2022-jp to shift_jis (needed for CHM
> > generation)
>
> No, it can't do that.
>
> > * I'm not sure, if it can generate pages like quickreference or
> > mod/index
>
> I'm not sure what these things are.. Could you describe them to me?
http://httpd.apache.org/docs-2.0/mod/quickreference.html
http://httpd.apache.org/docs-2.0/mod/index.html
(and some other)
The files are generated from the actual module files (we're going through
the tree and fetch desired information from the source xml files).
> > * It uses presentional markup, which is bad. We have quite clean
> > generated HTML documents, where the presention is made only via css.
>
> I don't believe it does use presentation markup. The HTML generated is
> clean as a whistle, save for
hmm, I saw things like <s> on the doco page (sure one doesn't need to use
it, but you loose a feature).
> > * XSLT is standardized. People don't need to learn yet another
> > formatting language and there's a lot of work already done out there.
>
> That's definitely true, but at my company we tried a few other similar
> things and didn't find them to be powerful enough.
We do work here quite well with an xslt/python/xalan combo for our live
servers :-) But agreed it's a lot of effort in the first place.
nd
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Doco - useful for Apache documentation project?
Posted by James Dodd <jd...@accucard.com>.
Hello,
> * I18N and charset issues are (basically) not a problem. I'm certain, doco
> has e.g. problems recoding iso-2022-jp to shift_jis (needed for CHM
> generation)
No, it can't do that.
> * I'm not sure, if it can generate pages like quickreference or mod/index
I'm not sure what these things are.. Could you describe them to me?
> * It uses presentional markup, which is bad. We have quite clean generated
> HTML documents, where the presention is made only via css.
I don't believe it does use presentation markup. The HTML generated is
clean as a whistle, save for
* a reference to a stylesheet (which does all the styling)
* a CSS class emitted for certain types of table and paragraph
If you're talking about a CSS snippet being in the document itself,
that's because it was put in there with an 'include'.
> * XSLT is standardized. People don't need to learn yet another
> formatting language and there's a lot of work already done out there.
That's definitely true, but at my company we tried a few other similar
things and didn't find them to be powerful enough.
In my opinion, XSLT and XML is very heavyweight for documentation, and
there's only really a benefit if you use a lot of metadata or want to
generate in multiple output formats (which you can do with Doco output
anyway, as it's XHTML and thus transformable).
> * besides some other reasons: we've already switched to XML. It would be a
> lot of effort to switch again to something else.
Well, thanks for your opinions, anyway!
Cheers,
James
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Doco - useful for Apache documentation project?
Posted by André Malo <nd...@perlig.de>.
* James Dodd <jd...@accucard.com> wrote:
> Just wondering whether 'Doco' may be of any use to the Apache
> documentation project.
> It's a lightweight markup syntax for converting text to HTML docs,
> and has lots of useful & powerful features.
>
> Documentation is at
>
> http://doco.sourceforge.net/
>
> And it can be downloaded from
>
> http://sourceforge.net/projects/doco
>
I've taken a look at it and I think it's not really sufficient. We use XML
for several reasons:
* I18N and charset issues are (basically) not a problem. I'm certain, doco
has e.g. problems recoding iso-2022-jp to shift_jis (needed for CHM
generation)
* I'm not sure, if it can generate pages like quickreference or mod/index
* It uses presentional markup, which is bad. We have quite clean generated
HTML documents, where the presention is made only via css.
* XSLT is standardized. People don't need to learn yet another
formatting language and there's a lot of work already done out there.
* besides some other reasons: we've already switched to XML. It would be a
lot of effort to switch again to something else.
all IMHO, of course.
nd
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org