[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
> Another issue I'd like to bring up is documentation. Not for 4.9.6,
> but longer term (5.0, though we'll want to get this sorted out well
> before then).
> I probably missed part of the discussion here over the past few
> months, so if someone has a link to point me too, that's fine too.
We decided in one of those IRC meetings to use pandoc. Look in the
docs/src folder to see the current pandoc documentation.
> There are two things: the documentation itself and the format its in.
> To start with the latter. Right now in docs we have the naturaldocs.
> That's ok, they look much better than most of the automatic from-
> source documentation that I've seen (*cough*doxygen*cough*), however,
> they are just HTML. Do we plan to provide documentation in the form
> of man and info pages as well (count me in for a vote to do that), if
> so how do we generate those? Windows users probably want .chm
> documentation, which I guess you get from the .html docs. This is
> mostly something to think about.
I guess we'll phase out the naturaldocs docs over time. They are rather
nice, but yes, not really enough for our purpose.
> By the way, is it just me or is there generated content in the
> repository? Despite not having touched anything in docs/ myself I got
> a message that there were local changes during at least one svn update.
> The second issue is the content. Right now what's there is mostly ok,
> but a bit rough. From a user perspective, I don't like the
> distinction "Include" and "Src", which are more meaningful to people
> working *on* Allgro as opposed to *with* Allegro. The organisation
> into categories could be better, right now there doesn't seem to have
> been much organised thought into what goes where.
Naturaldocs is limited to how you organize things. The menu entries can
be changed, but each source file is one entry. Moot point anyway unless
we change our mind about naturaldocs.
> Function descriptions are ok in as far as they're there, but a bit
> short. Allegro 4's documentation often has a Return value: heading,
> which I think is a must have. Even if it's blatantly obvious. Another
> thing that's missing are cross references, for instance from
> al_set_keyboard_leds() to "Keyboard modifier flags". Many of the
> "chapters" lack an introductory text, such as the "Events" section
> under Src/Release has (odd place for it in my opinion).
>
> So, is there a big plan when it comes to the documentation?
> Personally, I like A4's documentation in that
> * It begins with a general section "using Allegro" that gives a
> quick overview
> * Has chapters on each topic that again start with a quick
> overview, before going into function descriptions.
> * Has a few general sections
> I think these are ideas we should keep.
I agree completely.
> I can write out a proposal for how I'd do this, but again I'm not up
> to speed on what the current consensus is. Besides, does anyone even
> read e-mails that are this long?
>
Hehe. If you want something a bit longer to read.. here is the
transcript of the meeting where we decided on pandoc:
http://wiki.allegro.cc/index.php?title=Allegro_Hack_Day/2008_February_2
Actually, reading it again, it's not that long... tjaden proposed it,
and everyone agreed :)
--
Elias Pschernig <elias@xxxxxxxxxx>