C99 Stronghelp manual

I’m thinking of updating the existing “C-version5” Stronghelp manual to properly document the new features of the current C compiler. Several questions spring to mind:

1 – Does anyone know how to contact Neil Bingham (the original author) to ask if he minds me basing my work on his manual?

2 – What’s ROOL’s position on my using some of the documentation from the C header files? I’m not intending a massive cut and paste job, but I’m sure there will be cases where the description of a function in the header files is suitable for use in the manual, and it seems silly to rewrite things needlessly.

3 – Is anyone already working on such a project? Or has anyone already done it and I’ve not noticed?!

Thanks for any info!

how to contact Neil Bingham

He moved to Pace and was also registered with acornreunited.org.uk.

already working on such a project?

Chris Bazley’s previously done some work on it, although that may already be in the version you have.

Thanks for the info, I’ll try to contact Neil.

The manual by Chris Bazley you refer to is the Toolbox manual – I’m thinking of updating the manual for the standard C library. Chris – if you read this, could you confirm that you haven’t already done that please?

Also, is there a ‘standard’ repositry for SH manuals? I’ve checked the collection at http://www.riscos.info/downloads/stronghelp/manuals/
but there are also a few available through the RO packaging project.

is the Toolbox manual

OK, I missed that.

‘standard’ repositry for SH manuals

It’s ‘standard’ for Christian Ludlam’s collection and it would seem logical to at least mirror (if not merge) any other repositories there.

I’ve been thinking some more about this. I am now considering that the way to go about this, might be actually to add some markup to the compiler’s header files, and write a script to turn those header files into a SH manual.

The script could be added to the compiler build process so that the manual was always up to date with the documentation in the headers.

Opinions?

Well, after a few weeks thinking (and a holiday :) I’ve got a plan. I’ve got a simple Python script that scans a series of header files, looking for active comments, and outputs Stronghelp pages.

The active comments in the header files are deliberately very minimal:

/**fn: [name [...]] */  - start a new page describing a function
/**fn*/                 - end a function page
/**def: [name [...]] */ - start a new page describing a macro
/**def*/                - end a macro page

“Function” and “Macro” pages are basically the same, but they are listed in different places on the index page, which is also built automatically.

If a page name is not specified the scripts tries to identify the function or macro being described. If more than one page name is specified, the page is created with the first name, and links to it are created under the remaining names – this is to enable keyword lookup in StrongHelp.

So, for example, from the math.h header file, here’s the declaration of the “atan” function along with the active comments enclosing the contents we want on the SH page:

/**fn: */
double atan(double /*x*/);
float atanf(float /*x*/);
long double atanl(long double /*x*/);
   /* computes the principal value of the arc tangent of x */
   /* Returns: the arc tangent in the range -Pi/2 to Pi/2. */
/**fn*/

This creates the following SH page called “atan”:

atan
#Parent math/h
#wrap off
{fcode}double atan(double x);
float atanf(float x);
long double atanl(long double x);
{f}
#wrap on
computes the principal value of the arc tangent of x

Returns: the arc tangent in the range -Pi/2 to Pi/2.

Also two links are created to that page, called “atanf” and “atanl” so that keyword lookup on any of those three words will return this page.

Creating pages to describe macros works in exactly the same way. As an example of forcing a page name, rather than allowing the script to work it out, here’s another section from math.h:

/**def: HUGE_VAL HUGE_VALL DBL_MAX */
   /* HUGE_VAL equals DBL_MAX, and this is the return value for overflow */
   /* range errors in the C90 functions. Also, domain errors return */
   /* -HUGE_VAL = -DBL_MAX. */
/**def*/

This will create a page “HUGE_VAL” (and links to it called “HUGE_VALL” and “DBL_MAX”), and the contents of the page will just be the text in the comments.

My next steps are to refine the script a bit more, and add markup to all the standard library header files, with the ultimate goal of producing a comprehensive SH manual. There’s nothing to stop this system being used with any header files of course, and I’ll obviously commit my stuff to the cvs when it’s ready.

A couple of points – I’m aware that there are already fully featured systems to do this sort of thing (for example doxygen), but I decided to start from scratch for two reasons. Firstly, every existing system I looked at was rather complicated and would have taken a considerable effort to port to RISCOS. And secondly, none of them produce StrongHelp output so more work would have been needed.

I’ve deliberately kept the markup in the header files as minimal as possible – even so does anyone have objections to this scheme? Is is going to cause problems in the future for whoever maintains the compiler?

Basically, if you think this is a crap idea, please tell me now! :)

The only negative is that I’d rather have help in HTML than in StrongHelp, because StrongHelp is proprietary and restricted to RISC OS (AFAIK), whereas HTML is neither.

There’s no reason why I can’t adapt the script to produce HTML and SH, it sounds like a good idea.

restricted to RISC OS (AFAIK)

Cross-Platform StrongHelp Creator?

Cross-Platform StrongHelp Creator?

But why would you, when HTML does all that you want and is about as widely entrenched and cross-platform as you can get?

why would you

From the post, it sounds as if it’d be used in conjunction with cross-compilation. However, my post crossed with Rik’s HTML response and so now it’s not too relevant!

Without wishing to start an HTML vs StrongHelp war, the key advantage of SH is the keyword lookup system. However if both could be automatically compiled from the header files, there’s no reason not to have both :)

Ok here’s an early attempt at auto generated HTML from math.h:

Link removed because a new version is available, please see below.

Looks good.

Very good!

Were it me, I’d left justify the headings and the separator lines. That’s all I can find to object to.

Very useful :-) Maybe consider including unobtrusive links above each separator line back up to the Functions/Macros/Pragmas or whatever?

OK I’ve updated the file with new output. Added links back to the top of the page, left justified headers. Also added experimental links from words in the text to sections with the same name, a bit wiki-like.

I think my next step is going to be to add markup to the rest of the header files, and see how the result looks.

Also added experimental links from words in the text to sections with the same name, a bit wiki-like.

It looks like there’s already some stuff there which tries to manually link certain keywords – the nexttoward entry contains the text “equivalent to the <nextafter> functions”, and math_errhandling looks like it’s meant to link to errno & HUGE_VAL.

And while we’re on the subject of bugs, you might want to swap the &apos; entity for &#39; since apos doesn’t work in IE

Oops that ‘nextafter’ link-type thing was me playing around at an early stage of the project, I just added StrongHelp type links directly to the header file text as an experiment. I’ll diff against the original to ensure nothing like that makes its way into the finished product!

Or, I could remove the auto-linking and add explicit links to the text – the script can convert the SH style into HTML links if required.

Well, after much rewriting and fiddling, I’ve produced a usable first draft of a complete manual. Available in StrongHelp or HTML, it can be downloaded from http://www.btinternet.com/~rik.griffin/C99.html

You can also browse the HTML version online. Please let me know what you think – whether it be concerning errors or style.

Eventually, if this is judged to be useful, I’ll make the conversion script and the header file markup available. Whether it would be desirable to incorporate my modified header files into the RO source code is a question I shall leave for another day :)

I took a quick look at the StrongHelp manual and liked the look of it. Useful stuff, thanks!

I’ve now released the Python program I used to generate the manual. Rather grandly described as a “documentation generation system”, it’s available from http://www.btinternet.com/~rik.griffin/makehelp.html

You need Python 2.4.1 – it may work with other versions but I haven’t tested that.

Instructions are in the !Help file. Feedback, as always, is welcome!