Allegro.cc - Online Community

Allegro.cc Forums » Allegro Development » Documentation - minor issues

This thread is locked; no one can reply to it. rss feed Print
Documentation - minor issues
Polybios
Member #12,293
October 2010

I've found a list of minor issues I had made while going through the documentation some weeks ago. I've hoped I'd be able to look into these myself soon, but life keeps getting in the way of me digging deeper into the parts I don't know well yet. :( So I thought I'd post the list here at least.

Here goes:

Lacking documentation:

  • the meaning of ALLEGRO_MOUSE_EMULATION_* modes is not (really) documented (what do transparent, inclusive, exclusive, and compatible with 5.0 actually mean?)

  • the meaning of ALLEGRO_EVENT_VIDEO_* is not documented

  • the meaning of ALLEGRO_EVENT_AUDIO_* is not documented (those listed under ALLEGRO_AUDIO_EVENT_TYPE)

Unclear:

  • the question about ALLEGRO_PROGRAMMABLE_PIPELINE in the docs on al_attach_shader_source is unanswered (maybe move this info to display.txt anyway?)

  • the documentation on al_get_opengl_fbo is a bit ambiguous ("if it uses one" vs. "This has since been changed")

  • the documentation for al_attach_mixer_to_mixer and al_attach_mixer_to_voice is a bit unclear about the requirements for attaching

I've also encountered two API-related notes that probably should be decided about before 5.2:

  • ALLEGRO_JOYFLAGS: "this enum is a holdover from the old API and may be removed"

  • al_create_audio_recorder: "Allegro will internally buffer (...) (XXX: These settings need to be exposed via config or API calls.)"

That's it!

Generally speaking, I've personally found the documentation to be in very good shape and easily understandable. The only thing I'd consider mandatory for moving from "very good" to "excellent" would be a nice introductory paragraph to the section about the audio-addon.

Thank you for your patience.
P.

SiegeLord
Member #7,827
October 2006
avatar

Awesome, thanks! Something to get to once the critical things are taken care of.

"For in much wisdom is much grief: and he that increases knowledge increases sorrow."-Ecclesiastes 1:18
[SiegeLord's Abode][Codes]:[DAllegro5]:[RustAllegro]

Polybios
Member #12,293
October 2010

Of course! I can't thank you enough for prioritizing "Windows". :D
I just had it on my desk still.

Edgar Reynaldo
Member #8,592
May 2007
avatar

I'd like to add a request for .chm documentation if we could add it into the build process on windows. You would have to check for the html compiler, but really compiled html docs are so much easier to navigate with an index. There was someone who built .chm files for 5.1.8 I know because I'm still using them practically everyday but he wouldnt' sit down and describe the process to me and I haven't been able to grasp it yet.

Polybios
Member #12,293
October 2010

Peter made some suggestions about how to do that years ago.

with an index

By the way, the normal html docs also provide an index, there's even a searchfield with autosuggest done in javascript.

Thomas Fjellstrom
Member #476
June 2000
avatar

The pdf is searchable and has an index. I used to generate them automatically... I may set that up again at some point.

--
Thomas Fjellstrom - [website] - [email] - [Allegro Wiki] - [Allegro TODO]
"If you can't think of a better solution, don't try to make a better solution." -- weapon_S
"The less evidence we have for what we believe is certain, the more violently we defend beliefs against those who don't agree" -- https://twitter.com/neiltyson/status/592870205409353730

Edgar Reynaldo
Member #8,592
May 2007
avatar

But the PDF doesn't have interlinks does it? Like when it says see here there's no link to the topic?

And I didn't mean an index - sorry - I meant contents, a link to all the major topics at the left so you can change places quickly. I suppose the html docs have the same thing too but I just like the chm.

Elias
Member #358
May 2000

http://allegro5.org/refman.pdf

At least in Firefox, I can just click it, and it has contents to the left, and all links are clickable just like in the HTML.

{"name":"609387","src":"\/\/djungxnpq2nug.cloudfront.net\/image\/cache\/c\/4\/c4c8ecc67d2487a3f6729d2f88fa795b.png","w":1258,"h":926,"tn":"\/\/djungxnpq2nug.cloudfront.net\/image\/cache\/c\/4\/c4c8ecc67d2487a3f6729d2f88fa795b"}609387

--
"Either help out or stop whining" - Evert

Edgar Reynaldo
Member #8,592
May 2007
avatar

Hmm. Ok, well, I still don't really like PDF for the simple reason that Adobe Reader kind of sucks. It's gotten better, but giant PDFs take a long time to load and you can't copy paste very well out of PDF documents.

Thomas Fjellstrom
Member #476
June 2000
avatar

I agree that acrobat reader is a pile of shit. But okular is pretty decent if you don't need fancy form support. Chrome does a decent job of pdf viewing as well.

--
Thomas Fjellstrom - [website] - [email] - [Allegro Wiki] - [Allegro TODO]
"If you can't think of a better solution, don't try to make a better solution." -- weapon_S
"The less evidence we have for what we believe is certain, the more violently we defend beliefs against those who don't agree" -- https://twitter.com/neiltyson/status/592870205409353730

SiegeLord
Member #7,827
October 2006
avatar

I don't mind a CHM generator, somebody just has to do the work. I agree that a PDF is not a great replacement. Granted... it might be a bit of work, since A5's documentation generation is pretty complicated... but I'm sure it can be done.

In my ideal world, I'd actually have better web documentation... but that might be a lot more work than hacking in CHM support.

"For in much wisdom is much grief: and he that increases knowledge increases sorrow."-Ecclesiastes 1:18
[SiegeLord's Abode][Codes]:[DAllegro5]:[RustAllegro]

Go to: