[ Thread Index |
Date Index
| More lists.liballeg.org/allegro-developers Archives
]
On 5 Oct 2008, at 04:17, Peter Hull wrote:
In my mind the most important thing is to merge the fshook branch, the
the API is complete (I think) and we just need to work on implementing
missing functions in the platform-specific parts (for Mac, anyway,
others may already be done)
The other thing is a more comprehensive 'test' program that we can use
to check all parts of the API are working properly. That's quite a job
in itself.
I would like to add:
* Cleaning up the naming scheme of kcm_audio (I can do this)
* Improving allegro5-config. I've looked at this a little bit
(which reminds me, I need to commit a small cosmetic fix to
CMakeLists.txt). The problem is that, right now, allegro5-config --
libs gives me
-L/Users/eglebbk/lib -lallegd_s-4.9.5 /System/Library/Frameworks/
AppKit.framework /System/Library/Frameworks/IOKit.framework /System/
Library/Frameworks/OpenGL.framework /System/Library/Frameworks/
AGL.framework
which is wrong (note that there is a version number on
allegd_s-4.9.5, that was missing originally but it is present in the
library name itself). Instead of listing the location of the
frameworks it should say -framework OpenGL etc. CMake gets this right
when compiling the examples, but for allegro5-config we grab the list
of detected libraries from CMake itself, rather than the linker
options CMake produces based on that list. Here I need a bit of help
from someone who knows more about CMake than I do: how would I get
that list of linker options from CMake?
As I've already mentioned, I'd also like `allegro5-config --libs --
addon audio ttf iio...`, because that will a) safe me from having to
work out what those are called and more importantly b) mean I don't
have to figure out what external dependancies those depend on (-
framework OpenAL comes to mind). That's again something I can do,
once I've figured out the previous bit.
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.
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.
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.
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 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?
Evert