Get documentation into Octave/QHelp format

[apjanke]

• Convert the documentation in doc/ to texinfo
• Convert the helptext for all funtions and methods to texinfo
• Documentation-building scripts to turn those in to QHelp files, and add the PKG_ADD hack to load the QHelp manual
• Convert the Makefile to Octave package style
• Fix bugs!

The documentation-building scripts and Makefile can be taken from the Tablicious package.

Follows up #3.

[apjanke]

I'm tagging this as "help wanted" because this is just clerical work, and I don't like working with Texinfo. Maybe some kind soul will come along and save me from this onerous task.

[mariajcasas]

HI Andrew,
I've seen you are asking for some help with formatting some documentation and I think I could help you with this. Under /doc folder there is only UserGuide.md file. Is this the one that should be converted to texinfo?
It would be my first time doing this but this kind of tasks works for me.
I will start reading about textinfo and I will keep you up to date of my progress or failures!

Cheers
Maria J. Casas

[apjanke]

Hi Maria,

Glad you're interested!

There's only the UserGuide.md under /doc. But there is per-function and per-class "helptext" documentation in each of the public functions and classes in the library. (For example, this whole block.) All that will need to be converted to TexInfo as well.

If you want to see some examples, take a look at my Tablicious package - all its doco is in correct Octave-friendly Texinfo format. (And it's one of the few Octave packages that correctly supports class-level Texinfo documentation; that's an extension I added in to the package's doco-building scripts.)

[apjanke]

I decided I'm not so lazy that I can't do this. Work is proceeding on the convert-doco-to-texinfo branch: https://github.com/apjanke/octave-slf4o/tree/convert-doco-to-texinfo.

[apjanke]

Okay, I got the doco kind of converted to Texinfo format and merged it to master.

It's not entirely working:

• Some of the API Reference function/method doco is not showing up, even though there are section headers for those functions
• Too many "logger." prefixes for the objects; looks like the namespace is getting appended to them by the doco processor
• Building the QHelp project is not working. I'm getting this error:

>> master >  ~/l/r/o/doc >
$ make maintainer-clean; make all
rm -rf *.dvi *.eps html *.html *.info *.pdf *.ps *.png *.texi *.qhp *.qch *.qhc *.tmp images.mk
export SOURCE_DATE_EPOCH=`cat TIMESTAMP`; \
	perl ./mktexi.pl slf4o.texi.in ../INDEX slf4o.texi slf4o.qhp ../inst
perl ./mktexi.pl --check-texinfo-version
Texinfo version 6.7 is new enough
makeinfo --no-split -o slf4o.info slf4o.texi
makeinfo --html --no-split -o slf4o.html slf4o.texi
rm -rf html
makeinfo --html -o html slf4o.texi
texi2dvi --quiet --clean -o slf4o.dvi slf4o.texi
export SOURCE_DATE_EPOCH=`cat TIMESTAMP`; \
	texi2pdf --quiet --clean -o slf4o.pdf slf4o.texi
/usr/local/opt/qt/bin/qhelpgenerator slf4o.qhcp -o slf4o.qhc
Reading collection config file...
Generating help for slf4o.qhp...
Error in line 14: Expected '>' or '/', but got '[a-zA-Z]'.
make: *** [slf4o.qhc] Error 1

[mariajcasas]

Hi Andrew,

Not sure If I can help you with anything else now that you've done the work! hehehe

What I see is that the way you extract the "helptext" documentation of the library, can be useful for my project. So. I'll catch a glimpse and try to use it. Any tips!

Thanks a lot!
Cheers

[apjanke]

Feel free to take my helptext extractor code! The stuff you need is:

• .gitignore
• Makefile
• doc/Makefile
• doc/mktexi.pl
• doc/OctTexiDoc.pm
• doc/README.md
• doc/slf4o.qhcp
• doc/slf4o.texi.in

Edit the doc/slf4o.qhcp file to use the right file names for your package and rename it to <mypackage>.qhcp. Rename doc/slf4o.texi.in to <mypackage>.texi.in and change its contents as appropriate. The rest of the files are generic and should be usable if you drop them right in to another Octave package. You'll need to provide your own properly-formatted DESCRIPTION and INDEX files in the package root.

These scripts are based on the doco-generation stuff in various Octave Forge packages, but I've modified them to support namespaces and classdef files, and refactored the code.

Let me know how they work out for you! I'd be happy to fix them up if you have problems with them.

[apjanke]

Building the QHelp project is fixed now. Double-quotes in section names were producing invalid XML. The mktexi.pl stuff should be fixed to handle this case by escaping the quotes, but for now, I just removed the quotes from the section name.

[apjanke]

Oh! I forgot to add the special PKG_ADD/PKG_DEL files that make the manual available in the Octave GUI's documentation browser. Added in 03c1c35.

You'll want to grab and adapt those, too, if you're using my helptext extractor stuff.

[apjanke]

Aha: found a bug in the doco generation code: #13.

[apjanke]

Okay, I think this is all working now. Closing as fixed.

Let me know if you have any issues!