| Re: [AD] doc / makedoc suggestion |
[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
On 2004-06-05, Julien Cugnière <jcugniere@xxxxxxxxxx> wrote:
> "People don't read FAQs (but should)" is a well known fact :-)
> This gave me the following idea:
>
> Maybe a new optional section named "related FAQs" could be added
> to the function descriptions in the documentation, similar to the
> "see also" one. For example, d_bitmap_proc could have "Related
> FAQs: <Why can't I get d_bitmap_proc or d_icon_proc to work
> ?>". fade_out and co. could have "Related FAQs: <How can I fade
> the screen in a truecolor graphics mode?> ".
>
> What do people think ?
It is a nice idea for a future makedoc, because it is not possible to
implement this at the moment. The current makedoc format only allows
manual external references to document which are only available in
HTML based documentation. If that is not bad enough (info users
should be able to have the same feature, IMHO, but it is really
tricky), HTML generation of the faq entries is done based on their
text, rather than number or internal ID. This means that every time a
question is modified to have a better wording, the link doesn't work
any more. Not extremely difficult to handle, but you need somebody
worried about maintaining those external links. And whenever you
make a human do a monotonous work, only errors can be expected.
So at the moment it is esier to point users to the faq. BTW, your
first sentence should be "People don't read documentation".