[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
On 2011-09-16, Elias Pschernig <elias.pschernig@xxxxxxxxxx> wrote:
> 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.
Yeah, this is a bit of a problem. We could symlink or copy
ALLEGRO_EVENT_JOYSTICK_AXIS.3 -> ALLEGRO_EVENT.3
> > 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?
I implemented a smarter algorithm instead. The man page starts with
## API: and stops when the number of hashes is equal or less than the
number that we started with.
Peter