From: Peter W. <nov...@gm...> - 2011-09-17 00:42:40
|
On 2011-09-16, Elias Pschernig <eli...@gm...> 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 |