Re: [AD] pandoc links

[ Thread Index | Date Index | More lists.liballeg.org/allegro-developers Archives ]


On 2011-09-16, Elias Pschernig <elias.pschernig@xxxxxxxxxx> wrote:
> Before I try figuring it out myself - why do links like
> [ALLEGRO_EVENT_JOYSTICK_AXIS] not work in the documentation? It appears
> in the table of contents and can be linked to as
> http://www.liballeg.org/a5docs/refman/events.html#allegro_event_joystick_axis but I can't get pandoc to make a link to it from elsewhere in the documentation. And now with close to 30 events a "See also: ALLEGRO_EVENT" is getting a bit unhelpful.

The documentation system recognises "# API: blah" lines and generates
the html_refs and dummy_refs files to make the [syntax] work.

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

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.

- 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.

Peter




Mail converted by MHonArc 2.6.19+ http://listengine.tuxfamily.org/