From: Elias P. <eli...@gm...> - 2011-09-16 21:33:30
|
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); |