[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
On Sat, 2011-09-17 at 01:20 +1000, Peter Wang wrote:
> The documentation system recognises "# API: blah" lines and generates
> the html_refs and dummy_refs files to make the [syntax] work.
>
I see. So if I change
ALLEGRO_EVENT_JOYSTICK_AXIS
---------------------------
to
### API: ALLEGRO_EVENT_JOYSTICK_AXIS
it already works as I wanted (except it gets its own man page).
> Our man page writer starts writing a new man page when it sees "# API: blah"
> and stops at the next line beginning with "#".
> The headings for the individual event types are indicated with the
> underline syntax instead of hashes precisely to fool the man page writer
> into keeping the documentation for all event types on a single man page,
> which I thought was preferable (but debateable).
>
If we start adding things like
See also: [ALLEGRO_EVENT_JOYSTICK_AXIS]
then I guess it would not make much sense in the man documentation as
there would be no such topic. Hm.
> We have a couple of options.
>
> - figure out some other way to delineate man pages, then we can use
> # API: blah syntax for the event types.
>
I guess it would still have to be valid pandoc syntax, so we can't just
do things like say "###" starts a manpage but "###*" does not?
> - allow zero hashes before the "API:" so you can write
>
> API: ALLEGRO_EVENT_JOYSTICK_AXIS
> --------------------------------
> blah blah blah
>
> The only real downside is that there might be false positives.
>
Looks quite save to me. Does this look right?
--- a/docs/scripts/make_html_refs.c
+++ b/docs/scripts/make_html_refs.c
@@ -33,7 +33,7 @@ int main(int argc, char *argv[])
d_init(argc, argv);
while (d_getline(line)) {
- if (d_match(line, "^#+ API: *")) {
+ if (d_match(line, "^[ #]*API: *")) {
d_basename(d_filename, ".html", file);
name = d_after_match;
d_tolower(name, sec_id);