GrafX2 documentation (parsing helpfile.h)
Paul Onyschuk
dead?" thread. Especially interesting was parsing "helpfile.h" and
reusing data from this file. So I started hacking some awk script,
here is example HTML output [1], but first some description.
From the start I knew what interim format I wanted to use. Decision
to choose mdoc (one of the man pages format) was supported by few
factors. One important thing was 44 character long lines in
"helpfile.h" - this is no problem at all with mdoc because (quoting from
Practical UNIX Manuals [2]):
>
> Text lines are concatenated together when forming output (...)
>
Structure of mdoc page could be also easily generated:
- just add ".Ss" (subsection) macro at the begging of every
HELP_TITLE occurrence
- replace empty HELP_TEXT occurrence with ".Pp" macro (new paragraph)
- add ".Dl" macro (intended line) for HELP_BOLD
Just look at mdoc file [3], similarity to "helpfile.h" is huge. Some
other thing were needed as removing multiple ".Pp" occurrences or
removing ".Pp" before or after ".Ss" macro (those were replaced by ".").
I also picked up mdoc, because great tool for formating mdoc pages
exist. It is called mdocml [4] or simply mandoc. It provides multiple
outputs (PDF, postscript, HTML, simple text), and when using mdoc format
(which is structural format) output is in good quality.
Although there is one down side. My AWK script is very hacky. Mdoc
page is generated from "helpfile.h" automatically, but I realized that
it is wrong thing to do. I spend much of the time fighting with C code
writing script. So I won't share the script.
The proper solution in my opinion would be writing C code to use
"helpfile.h" directly. Adding simple program to GrafX2 Makefile
(optional like "make manpage"), which prints output of helpfile.h to
stdout shouldn't be much problem. Conditionals for generation mdoc
format are pretty simple, beside that some #ifdef section could be
added to "helpfile.h" to help with some preformed section e.g.
brushes. Including default key-bindings should be also possible.
The problem lies in my C coding skills, which are very poor. I think
that I know mdoc format very well and grasped some knowledge of
"helpfile.h". With help from someone working with GrafX2, we could
cook up good looking documentation generated from "helpfile.h" in no
time.
I would prefer contact through IRC, to speed things up
(communication). Anyway end result should be pleasing: more detailed
man page and multiple other formats, using same/available data.
[1] http://blinkkin.github.com/grafx2/grafx2.html
[2] http://manpages.bsd.lv/
[3] http://blinkkin.github.com/grafx2/grafx2.1
[4] http://mdocml.bsd.lv/