HTML documentation - one file per function

[John Swensen]

Is there a way to process the docstrings so as to create one file per  
function?  I have started work on OctaveDE again and want to make a  
help browser.  I can simply use the existing HTML documentation, but  
would prefer to have it in the format of one HTML file per function.  
I would then try to work in cross referencing and the like.  Has  
someone already done this before?

John Swensen

[Søren Hauberg]

lør, 03 05 2008 kl. 11:54 -0400, skrev John Swensen:
> Is there a way to process the docstrings so as to create one file per  
> function?  I have started work on OctaveDE again and want to make a  
> help browser.  I can simply use the existing HTML documentation, but  
> would prefer to have it in the format of one HTML file per function.  
> I would then try to work in cross referencing and the like.  Has  
> someone already done this before?

You mean like the Function Reference at the Octave-Forge web site,
http://octave.sourceforge.net/doc/index.html ?

Søren

[John Swensen]

Yep.  Exactly like that.  Thanks for pointing out what I already  
should have know ;)

John


On May 3, 2008, at 12:06 PM, Søren Hauberg wrote:

> lør, 03 05 2008 kl. 11:54 -0400, skrev John Swensen:
>> Is there a way to process the docstrings so as to create one file per
>> function?  I have started work on OctaveDE again and want to make a
>> help browser.  I can simply use the existing HTML documentation, but
>> would prefer to have it in the format of one HTML file per function.
>> I would then try to work in cross referencing and the like.  Has
>> someone already done this before?
>
> You mean like the Function Reference at the Octave-Forge web site,
> http://octave.sourceforge.net/doc/index.html ?
>
> Søren
>

[John Swensen]

On May 3, 2008, at 12:06 PM, Søren Hauberg wrote:

> lør, 03 05 2008 kl. 11:54 -0400, skrev John Swensen:
>> Is there a way to process the docstrings so as to create one file per
>> function?  I have started work on OctaveDE again and want to make a
>> help browser.  I can simply use the existing HTML documentation, but
>> would prefer to have it in the format of one HTML file per function.
>> I would then try to work in cross referencing and the like.  Has
>> someone already done this before?
>
> You mean like the Function Reference at the Octave-Forge web site,
> http://octave.sourceforge.net/doc/index.html ?
>
> Søren
>

As a follow-on question, who is the wizard who wrote the code to parse  
all the DOCSTRINGS for Octave and Octave-forge into this HTML format?  
Do you know if there is way to convert the texinfo stuff to docbook?  
This would make the creation of the help browser with search  
capabilities infinitely easier.

John

[Ben Abbott]

On May 5, 2008, at 10:05 PM, John Swensen wrote:

>
> On May 3, 2008, at 12:06 PM, Søren Hauberg wrote:
>
>> lør, 03 05 2008 kl. 11:54 -0400, skrev John Swensen:
>>> Is there a way to process the docstrings so as to create one file  
>>> per
>>> function?  I have started work on OctaveDE again and want to make a
>>> help browser.  I can simply use the existing HTML documentation, but
>>> would prefer to have it in the format of one HTML file per function.
>>> I would then try to work in cross referencing and the like.  Has
>>> someone already done this before?
>>
>> You mean like the Function Reference at the Octave-Forge web site,
>> http://octave.sourceforge.net/doc/index.html ?
>>
>> Søren
>>
> As a follow-on question, who is the wizard who wrote the code to  
> parse all the DOCSTRINGS for Octave and Octave-forge into this HTML  
> format?  Do you know if there is way to convert the texinfo stuff to  
> docbook?  This would make the creation of the help browser with  
> search capabilities infinitely easier.
>
> John

I have no experience in this, but doesn't makeinfo do that?

http://linux.die.net/man/1/makeinfo

makeinfo --docbook foo.texi

Ben

[Søren Hauberg]

man, 05 05 2008 kl. 22:05 -0400, skrev John Swensen:

> On May 3, 2008, at 12:06 PM, Søren Hauberg wrote:
>
> > lør, 03 05 2008 kl. 11:54 -0400, skrev John Swensen:
> >> Is there a way to process the docstrings so as to create one file per
> >> function?  I have started work on OctaveDE again and want to make a
> >> help browser.  I can simply use the existing HTML documentation, but
> >> would prefer to have it in the format of one HTML file per function.
> >> I would then try to work in cross referencing and the like.  Has
> >> someone already done this before?
> >
> > You mean like the Function Reference at the Octave-Forge web site,
> > http://octave.sourceforge.net/doc/index.html ?
> >
> > Søren
> >
> As a follow-on question, who is the wizard who wrote the code to parse  
> all the DOCSTRINGS for Octave and Octave-forge into this HTML format?  
> Do you know if there is way to convert the texinfo stuff to docbook?  
> This would make the creation of the help browser with search  
> capabilities infinitely easier.

We're using 'makeinfo' for that. If you checkout Octave-Forge from SVN
you can see how we generate the HTML files by going through 'make
www' (or is it 'make doc', I can never remember...). I must warn you
that the build process of the documentation is fairly complex.

Søren

[David Bateman]

John Swensen wrote:

>
> On May 3, 2008, at 12:06 PM, Søren Hauberg wrote:
>
>> lør, 03 05 2008 kl. 11:54 -0400, skrev John Swensen:
>>> Is there a way to process the docstrings so as to create one file per
>>> function?  I have started work on OctaveDE again and want to make a
>>> help browser.  I can simply use the existing HTML documentation, but
>>> would prefer to have it in the format of one HTML file per function.
>>> I would then try to work in cross referencing and the like.  Has
>>> someone already done this before?
>>
>> You mean like the Function Reference at the Octave-Forge web site,
>> http://octave.sourceforge.net/doc/index.html ?
>>
>> Søren
>>
> As a follow-on question, who is the wizard who wrote the code to parse
> all the DOCSTRINGS for Octave and Octave-forge into this HTML format?  

It was written by at least 4 people that I know of, which is why its a
mix of m4, perl, python and Makefile magic. Cleaning it up into a single
language with some makefiles might be nice, particularly getting rid of
the m4 as that part of the build is slow. However, this is a low
priority as it works now.

> Do you know if there is way to convert the texinfo stuff to docbook?
> This would make the creation of the help browser with search
> capabilities infinitely easier.
As Ben said "makeinfo --docbook" will be the basic method. However,
there are some embedded "@if{tex,html,info}" sections in some of the
help strings and so to get docbook to build correctly maybe you'd need
one of the "--ifhtml", "--iftex", etc commands to makeinfo to get some
additional text to be included so that the help strings make sense. A
grep in doc/Makefile and doc/htdocs/Makefile for makeinfo will find the
bits of the Makefiles that'll need to be copied to a docbook target to
get this to work.

Regards
David



>
> John
>


--
David Bateman                                David.Bateman@...
Motorola Labs - Paris                        [phone] (Ph)
Parc Les Algorithmes, Commune de St Aubin    [phone] (Mob)
91193 Gif-Sur-Yvette FRANCE                  [phone] (Fax)

The information contained in this communication has been classified as:

[x] General Business Information
[ ] Motorola Internal Use Only
[ ] Motorola Confidential Proprietary

[Søren Hauberg]

Quoting David Bateman <David.Bateman@...>:
> It was written by at least 4 people that I know of, which is why its a
> mix of m4, perl, python and Makefile magic. Cleaning it up into a single
> language with some makefiles might be nice, particularly getting rid of
> the m4 as that part of the build is slow. However, this is a low
> priority as it works now.

Actually, I'd rather not get rid of the m4 part as this is also what  
the octave.org web site uses. At some point (you know, that point  
where I have some spare time...) I'd like to see some of the  
Octave-Forge website scripts used to build part of the octave.org  
website. Specifically, I think it would be nice to use these scripts  
to build the manual, and possibly also have the function reference on  
octave.org.

Søren

[David Bateman]

soren@... wrote:

> Quoting David Bateman <David.Bateman@...>:
>> It was written by at least 4 people that I know of, which is why its a
>> mix of m4, perl, python and Makefile magic. Cleaning it up into a single
>> language with some makefiles might be nice, particularly getting rid of
>> the m4 as that part of the build is slow. However, this is a low
>> priority as it works now.
>
> Actually, I'd rather not get rid of the m4 part as this is also what
> the octave.org web site uses. At some point (you know, that point
> where I have some spare time...) I'd like to see some of the
> Octave-Forge website scripts used to build part of the octave.org
> website. Specifically, I think it would be nice to use these scripts
> to build the manual, and possibly also have the function reference on
> octave.org.
>

The m4 part takes more than 80% of the build time of the docs and its
only used to to do regexp replacements, that might be done in the
make_index script itself. I'd vote to do it there and do the same thing
for the octave website...

Cheers
David




--
David Bateman                                David.Bateman@...
Motorola Labs - Paris                        [phone] (Ph)
Parc Les Algorithmes, Commune de St Aubin    [phone] (Mob)
91193 Gif-Sur-Yvette FRANCE                  [phone] (Fax)

The information contained in this communication has been classified as:

[x] General Business Information
[ ] Motorola Internal Use Only
[ ] Motorola Confidential Proprietary

[John Swensen]

On May 3, 2008, at 12:06 PM, Søren Hauberg wrote:

> lør, 03 05 2008 kl. 11:54 -0400, skrev John Swensen:
>> Is there a way to process the docstrings so as to create one file per
>> function?  I have started work on OctaveDE again and want to make a
>> help browser.  I can simply use the existing HTML documentation, but
>> would prefer to have it in the format of one HTML file per function.
>> I would then try to work in cross referencing and the like.  Has
>> someone already done this before?
>
> You mean like the Function Reference at the Octave-Forge web site,
> http://octave.sourceforge.net/doc/index.html ?
>
> Søren
>

Would it be too much to ask someone who has access to the webserver to  
zip/tgz up all the HTML from the "Function Reference" portion of the  
website and send it to me offline.  I have been fighting trying to get  
it to build off-and-on for 2 days now and can't get it to do all of  
it.  I have the DOCSTRINGS from octave in place, but it won't generate  
the pages for interpreter functions.

I wrote a simple little help viewer (in GTK since the rest of OctaveDE  
is in that also) that uses a full-text search library called Xapian to  
index all the files.  Currently it only works on-line; e.g. I index  
the files to create a local search database and then simply direct  
them to the octave.sourceforge.net website.  Needless to say, I would  
like a complete set of the website HTML files so the index database  
will be complete.

John Swensen

[David Bateman]

John Swensen wrote:

>
> On May 3, 2008, at 12:06 PM, Søren Hauberg wrote:
>
>> lør, 03 05 2008 kl. 11:54 -0400, skrev John Swensen:
>>> Is there a way to process the docstrings so as to create one file per
>>> function?  I have started work on OctaveDE again and want to make a
>>> help browser.  I can simply use the existing HTML documentation, but
>>> would prefer to have it in the format of one HTML file per function.
>>> I would then try to work in cross referencing and the like.  Has
>>> someone already done this before?
>>
>> You mean like the Function Reference at the Octave-Forge web site,
>> http://octave.sourceforge.net/doc/index.html ?
>>
>> Søren
>>
>
> Would it be too much to ask someone who has access to the webserver to
> zip/tgz up all the HTML from the "Function Reference" portion of the
> website and send it to me offline.  I have been fighting trying to get
> it to build off-and-on for 2 days now and can't get it to do all of
> it.  I have the DOCSTRINGS from octave in place, but it won't generate
> the pages for interpreter functions.

You need to have a directory hierarchy

<toplevel>/octave-forge
<toplevel>/octave

Where the octave directory is built.. The interpreter functions then
found by running the built version of Octave in the directory under the
octave-forge directory.

Sorry however I don't have a built version at the moment.

D.


--
David Bateman                                David.Bateman@...
Motorola Labs - Paris                        [phone] (Ph)
Parc Les Algorithmes, Commune de St Aubin    [phone] (Mob)
91193 Gif-Sur-Yvette FRANCE                  [phone] (Fax)

The information contained in this communication has been classified as:

[x] General Business Information
[ ] Motorola Internal Use Only
[ ] Motorola Confidential Proprietary

[John Swensen]

On May 7, 2008, at 11:08 AM, David Bateman wrote:

>>
> You need to have a directory hierarchy
>
> <toplevel>/octave-forge
> <toplevel>/octave
>
> Where the octave directory is built.. The interpreter functions then
> found by running the built version of Octave in the directory under  
> the
> octave-forge directory.
>
> Sorry however I don't have a built version at the moment.
>
> D.

That is what I did and it built the documentation for the octave/
scripts/DOCSTRINGS fine, just not the documentation for octave/src/
DOCSTRINGS

John