|
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:
Unclear:
I've also encountered two API-related notes that probably should be decided about before 5.2:
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. |
SiegeLord
Member #7,827
October 2006
|
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 |
Polybios
Member #12,293
October 2010
|
Of course! I can't thank you enough for prioritizing "Windows". |
Edgar Reynaldo
Major Reynaldo
May 2007
|
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. My Website! | EAGLE GUI Library Demos | My Deviant Art Gallery | Spiraloid Preview | A4 FontMaker | Skyline! (Missile Defense) Eagle and Allegro 5 binaries | Older Allegro 4 and 5 binaries | Allegro 5 compile guide |
Polybios
Member #12,293
October 2010
|
Peter made some suggestions about how to do that years ago. Edgar Reynaldo said: 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
|
The pdf is searchable and has an index. I used to generate them automatically... I may set that up again at some point. -- |
Edgar Reynaldo
Major Reynaldo
May 2007
|
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. My Website! | EAGLE GUI Library Demos | My Deviant Art Gallery | Spiraloid Preview | A4 FontMaker | Skyline! (Missile Defense) Eagle and Allegro 5 binaries | Older Allegro 4 and 5 binaries | Allegro 5 compile guide |
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"} -- |
Edgar Reynaldo
Major Reynaldo
May 2007
|
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. My Website! | EAGLE GUI Library Demos | My Deviant Art Gallery | Spiraloid Preview | A4 FontMaker | Skyline! (Missile Defense) Eagle and Allegro 5 binaries | Older Allegro 4 and 5 binaries | Allegro 5 compile guide |
Thomas Fjellstrom
Member #476
June 2000
|
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. -- |
SiegeLord
Member #7,827
October 2006
|
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 |
|