You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@httpd.apache.org by rb...@covalent.net on 2000/07/21 01:21:14 UTC
Using DOC++ for Apache docs.
Because a few weeks ago, everybody seemed to agree that the pod was ugly,
I have begun to investigate other options for in-code documentation.
My first stop today was DOC++. I really dislike this.
DOC++ was written for C++ and Java, and this shows. It expects a
class hierarchy. In every HTML page that is displayed, DOC++ puts a link
for a "Heirarchy of classes", which in Apache will never be linked to
anything, because we have no classes.
I have been unable to insert formatting in the HTML output. I have
tried, and I will continue to try, but the HTML output refuses to pay
attention to my formatting tags.
Our options are limited for what we output. Pod has a lot of
different filters to generate different output formats. DOC++ can
generate HTML and Tex. This may be enough, I don't know.
I will continue to research more options for putting docs in our code. If
you have a favorite method of doing this, please let me know. As I
investigate an option, I will be compiling a web page that describes them
all, and then we can have an informed discussion of this.
Expect the web page sometime next week.
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Using DOC++ for Apache docs.
Posted by Greg Stein <gs...@lyra.org>.
On Sat, Jul 22, 2000 at 10:41:20AM -0700, rbb@covalent.net wrote:
> > Note: I believe the only important output is HTML. As long as we can do
> > that, then we're set.
>
> Quick question about this. Aren't there tools to go from HTML to just
> about any other format? So, even if ScanDoc can't generate anything other
> than HTML, we aren't limited to HTML.
There are, but I would think that the HTML generation loses semantic
information which could be used to create, say, RTF.
For example, we go from @param to some HTML. Whoops. The RTF doesn't know
that <dt>the_file</dt> represents a parameter.
We can certainly add (non-standard) HTML tags in there. Say
<dt><ap-param>the_file</ap-param></dt>, but that is certainly less
efficient.
We're a web server and deal with web pages. HTML seems about right :-)
I would guess that we could get ScanDoc to produce XML if we really needed a
format that retained semantic information. But that can probably deferred
until a need is discovered.
Cheers,
-g
--
Greg Stein, http://www.lyra.org/
Re: Using DOC++ for Apache docs.
Posted by rb...@covalent.net.
> Note: I believe the only important output is HTML. As long as we can do
> that, then we're set.
Quick question about this. Aren't there tools to go from HTML to just
about any other format? So, even if ScanDoc can't generate anything other
than HTML, we aren't limited to HTML.
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Using DOC++ for Apache docs.
Posted by rb...@covalent.net.
On Wed, 26 Jul 2000, Ben Laurie wrote:
> rbb@covalent.net wrote:
> >
> > Yes, I want the docs embedded in the source. I was just talking to Tony,
> > and we can probably change the template file that scandoc uses to output
> > DocBook however. This gives us the best of both worlds. :-)
>
> +1!
Quick comment about this. I am currently working on getting docs into the
code. Please, others feel free to help. Once that is done, I will work
on changing the ScanDoc template to output DocBook (again, others are more
than welcome to help with this).
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Using DOC++ for Apache docs.
Posted by Ben Laurie <be...@algroup.co.uk>.
rbb@covalent.net wrote:
>
> Yes, I want the docs embedded in the source. I was just talking to Tony,
> and we can probably change the template file that scandoc uses to output
> DocBook however. This gives us the best of both worlds. :-)
+1!
Cheers,
Ben.
--
http://www.apache-ssl.org/ben.html
Coming to ApacheCon Europe 2000? http://apachecon.com/
Re: Using DOC++ for Apache docs.
Posted by rb...@covalent.net.
Yes, I want the docs embedded in the source. I was just talking to Tony,
and we can probably change the template file that scandoc uses to output
DocBook however. This gives us the best of both worlds. :-)
Ryan
On Tue, 25 Jul 2000, Rasmus Lerdorf wrote:
> > linux-kernel is using something called docbook... all i know is that i
> > have all the tools for it on my rh62 box, but not sure where to find more
> > info.
>
> The PHP Project uses DocBook-XML as well. But it isn't really designed to
> handle documentation embedded in source code, which is what I think Ryan
> is after. DocBook is great though.
>
> -Rasmus
>
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Using DOC++ for Apache docs.
Posted by Rasmus Lerdorf <ra...@apache.org>.
> linux-kernel is using something called docbook... all i know is that i
> have all the tools for it on my rh62 box, but not sure where to find more
> info.
The PHP Project uses DocBook-XML as well. But it isn't really designed to
handle documentation embedded in source code, which is what I think Ryan
is after. DocBook is great though.
-Rasmus
Re: Using DOC++ for Apache docs.
Posted by dean gaudet <dg...@arctic.org>.
linux-kernel is using something called docbook... all i know is that i
have all the tools for it on my rh62 box, but not sure where to find more
info.
-dean
Re: Using DOC++ for Apache docs.
Posted by Greg Stein <gs...@lyra.org>.
+1 on ScanDoc. I'm familiar with the format (autoduck looks the same).
Basically, anything is going to be easier/better than the perldoc stuff
today :-)
Note: I believe the only important output is HTML. As long as we can do
that, then we're set.
[ yes, I'm sure people have other opinions; no, I don't care to start a
discussion on this. it is just a background point for part of my selection
process. "can" and "need" are distinct. I tend to focus on "need" ]
Cheers,
-g
On Fri, Jul 21, 2000 at 10:04:31AM -0700, rbb@covalent.net wrote:
>
> My initial analysis for documentation is done.
>
> I have put examples and pros and cons for the packages I could find at:
>
> http://www.apache.org/~rbb/docs
>
> The only package I didn't include was kdoc, because it didn't offer
> anything new that I could see. The four options we have based on my VERY
> rough research are DOC++, doxygen, scandoc, and pod.
>
> My own preference is to use scandoc for our documentation. It looks like
> DOC++ (and therefor JAVADOC), but we have more control over the
> output.
>
> I expect that if we use ScanDoc, we will create our own templates, and use
> our own images, but that is easy to change at any time.
>
> So, can we vote and decide how to store our docs in the code please. Once
> we have a decision, I am likely to hack up a perl script to convert our
> docs for APR.
>
> I will tally any votes people send to the list, and report the decision in
> a few days.
>
> Ryan
>
>
>
> On Fri, 21 Jul 2000, Greg Marr wrote:
>
> > At 10:49 AM 07/21/2000, rbb@covalent.net wrote:
> > > > I don't know how easy it is, but autoduck/autodoc supposedly can
> > > be
> > > > modified to output other formats. It currently only output RTF,
> > > DOC,
> > > > and HLP. I don't know how much it is tied to the PC though.
> > > >
> > > > You should be able to find it by searching for "Eric Artzt" (the
> > > > author) in any major search engine. If you have a problem finding
> > > > it, I probably have a zip somewhere.
> > >
> > >Thanks, I'll add it to my list.
> >
> > I won't be around next week, so I found the zip and dropped it at
> > http://www.wpi.edu/~gregm/autoduck.zip
> > I also zipped up some files I modified locally that make it easier to
> > find errors in the autoduck commenting that break builds
> > http://www.wpi.edu/~gregm/autoduck-mods.zip
> >
> > --
> > Greg Marr
> > gregm@alum.wpi.edu
> > "We thought you were dead."
> > "I was, but I'm better now." - Sheridan, "The Summoning"
> >
>
>
> _______________________________________________________________________________
> Ryan Bloom rbb@apache.org
> 406 29th St.
> San Francisco, CA 94131
> -------------------------------------------------------------------------------
--
Greg Stein, http://www.lyra.org/
Re: Using DOC++ for Apache docs.
Posted by rb...@covalent.net.
On Fri, 21 Jul 2000 rbb@covalent.net wrote:
>
> My initial analysis for documentation is done.
>
> I have put examples and pros and cons for the packages I could find at:
>
> http://www.apache.org/~rbb/docs
BTW, the packages can be found at http://www.apache.org/~rbb/docs/packages
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Using DOC++ for Apache docs.
Posted by rb...@covalent.net.
My initial analysis for documentation is done.
I have put examples and pros and cons for the packages I could find at:
http://www.apache.org/~rbb/docs
The only package I didn't include was kdoc, because it didn't offer
anything new that I could see. The four options we have based on my VERY
rough research are DOC++, doxygen, scandoc, and pod.
My own preference is to use scandoc for our documentation. It looks like
DOC++ (and therefor JAVADOC), but we have more control over the
output.
I expect that if we use ScanDoc, we will create our own templates, and use
our own images, but that is easy to change at any time.
So, can we vote and decide how to store our docs in the code please. Once
we have a decision, I am likely to hack up a perl script to convert our
docs for APR.
I will tally any votes people send to the list, and report the decision in
a few days.
Ryan
On Fri, 21 Jul 2000, Greg Marr wrote:
> At 10:49 AM 07/21/2000, rbb@covalent.net wrote:
> > > I don't know how easy it is, but autoduck/autodoc supposedly can
> > be
> > > modified to output other formats. It currently only output RTF,
> > DOC,
> > > and HLP. I don't know how much it is tied to the PC though.
> > >
> > > You should be able to find it by searching for "Eric Artzt" (the
> > > author) in any major search engine. If you have a problem finding
> > > it, I probably have a zip somewhere.
> >
> >Thanks, I'll add it to my list.
>
> I won't be around next week, so I found the zip and dropped it at
> http://www.wpi.edu/~gregm/autoduck.zip
> I also zipped up some files I modified locally that make it easier to
> find errors in the autoduck commenting that break builds
> http://www.wpi.edu/~gregm/autoduck-mods.zip
>
> --
> Greg Marr
> gregm@alum.wpi.edu
> "We thought you were dead."
> "I was, but I'm better now." - Sheridan, "The Summoning"
>
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Using DOC++ for Apache docs.
Posted by Greg Marr <gr...@alum.wpi.edu>.
At 10:49 AM 07/21/2000, rbb@covalent.net wrote:
> > I don't know how easy it is, but autoduck/autodoc supposedly can
> be
> > modified to output other formats. It currently only output RTF,
> DOC,
> > and HLP. I don't know how much it is tied to the PC though.
> >
> > You should be able to find it by searching for "Eric Artzt" (the
> > author) in any major search engine. If you have a problem finding
> > it, I probably have a zip somewhere.
>
>Thanks, I'll add it to my list.
I won't be around next week, so I found the zip and dropped it at
http://www.wpi.edu/~gregm/autoduck.zip
I also zipped up some files I modified locally that make it easier to
find errors in the autoduck commenting that break builds
http://www.wpi.edu/~gregm/autoduck-mods.zip
--
Greg Marr
gregm@alum.wpi.edu
"We thought you were dead."
"I was, but I'm better now." - Sheridan, "The Summoning"
Re: Using DOC++ for Apache docs.
Posted by rb...@covalent.net.
> I don't know how easy it is, but autoduck/autodoc supposedly can be
> modified to output other formats. It currently only output RTF, DOC,
> and HLP. I don't know how much it is tied to the PC though.
>
> You should be able to find it by searching for "Eric Artzt" (the
> author) in any major search engine. If you have a problem finding
> it, I probably have a zip somewhere.
Thanks, I'll add it to my list.
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Using DOC++ for Apache docs.
Posted by Greg Marr <gr...@alum.wpi.edu>.
At 07:41 PM 07/20/2000, Ryan Bloom wrote:
>scandoc -- Looks a lot like doc++, except the resulting docs can be
> formatted using a template file. This may be cool, or
> it may
> suck, but I'm looking forward to playing with it.
>
>Are there any packages I have missed?
I don't know how easy it is, but autoduck/autodoc supposedly can be
modified to output other formats. It currently only output RTF, DOC,
and HLP. I don't know how much it is tied to the PC though.
You should be able to find it by searching for "Eric Artzt" (the
author) in any major search engine. If you have a problem finding
it, I probably have a zip somewhere.
--
Greg Marr
gregm@alum.wpi.edu
"We thought you were dead."
"I was, but I'm better now." - Sheridan, "The Summoning"
Re: Using DOC++ for Apache docs.
Posted by rb...@covalent.net.
On Sat, 22 Jul 2000, Ben Laurie wrote:
> rbb@covalent.net wrote:
> > doxygen -- Uses all comments in the code as documentation, except those
> > surrounded by DoxyGen Macros. This feels like a bad idea to
> > me.
>
> Are you sure? I thought they had to be specially marked?
Yeah, I looked at this especially closely because I couldn't believe it
either. Doxygen docs say they use all comments except those in special
#ifdef sections. I couldn't test it because I don't have QT installed on
my machine, and Doxygen requires QT in order to build. This was another
strike against them.
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------
Re: Using DOC++ for Apache docs.
Posted by Ben Laurie <be...@algroup.co.uk>.
rbb@covalent.net wrote:
> doxygen -- Uses all comments in the code as documentation, except those
> surrounded by DoxyGen Macros. This feels like a bad idea to
> me.
Are you sure? I thought they had to be specially marked?
Cheers,
Ben.
--
http://www.apache-ssl.org/ben.html
Coming to ApacheCon Europe 2000? http://apachecon.com/
Re: Using DOC++ for Apache docs.
Posted by rb...@covalent.net.
BTW, so that I don't get multiple requests for the same doc package, here
is what I am currently investigating and my first impression of them:
pod -- The docs are ugly in the header file, but the results are
relatively clean.
doc++ -- The docs are clean in the header files, but the generated pages
are pretty ugly.
doxygen -- Uses all comments in the code as documentation, except those
surrounded by DoxyGen Macros. This feels like a bad idea to
me.
scandoc -- Looks a lot like doc++, except the resulting docs can be
formatted using a template file. This may be cool, or it may
suck, but I'm looking forward to playing with it.
Are there any packages I have missed?
Ryan
_______________________________________________________________________________
Ryan Bloom rbb@apache.org
406 29th St.
San Francisco, CA 94131
-------------------------------------------------------------------------------