Re: [AD] pandoc links

[Elias P. <eli...@gm...>]

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);