| | [ Return to Bugs & Features | Roadmap 1.1 | SVN ⇄ GIT ]
STR #1319
| Application: | FLTK Library |
|---|
| Status: | 1 - Closed w/Resolution |
|---|
| Priority: | 2 - Low, e.g. a documentation error or undocumented side-effect |
|---|
| Scope: | 3 - Applies to all machines and operating systems |
|---|
| Subsystem: | Documentation |
|---|
| Summary: | Suggestion for documentation index |
|---|
| Version: | 1.1.7 |
|---|
| Created By: | wilson.afn |
|---|
| Assigned To: | matt |
|---|
| Fix Version: | 1.1-current (SVN: v5353) |
|---|
| Update Notification: | |
|---|
Trouble Report Files:
Trouble Report Comments:
| |
| #1 | wilson.afn
06:22 Jun 08, 2006 |
| All the links under "Methods" are malformed. I imagine "HREF=" is missing its "#". | |
| |
| #2 | wilson.afn
12:59 Jun 08, 2006 |
| Here's a first cut at an index for documentation/*.html. I got justly chastised the other day for not being able to find Fl_Widget::position(), so I decided to see if I could whip up an index. The result, baz.htm, should be placed into the documentation subdirectory. It was generated completely by a python script which I intend to submit.
Python has a lot of help parsing HTML, but not much for writing it. I *hate* HTML, so I would appreciate advice on how the thing could be further tarted up. | |
| |
| #3 | matt
23:27 Jun 12, 2006 |
| The first issue is fixed in SVN and will be in Friday's snapshot.
*Please* post other bugs or suggestions in a separate STR. I will keep this one and rename the title, but normally I would just throw it out after fixing the bug.
I am not entirely clear how your submitted index would have helped to find the function you were looking for without knowing its name. Please give me some details.
Thanks for the contribution. | |
| |
| #4 | matt
23:40 Jun 12, 2006 |
| I would like to suggest links to all inherited functions. I am not sure if that would clutter documentation too much and I would like to get the other developers opinions on this. See attached file for Fl_Box. | |
| |
| #5 | mike
04:22 Jun 13, 2006 |
| I link adding links to all of the parent methods will just clutter things up and will be a maintenance nightmare.
We might be able to do something like this with the Doxygen stuff we use with 2.0, but I'm -1 on doing this for 1.1. | |
| |
| #6 | wilson.afn
07:19 Jun 13, 2006 |
| Matt asked how indexes help find things.
In my specific case, Greg used the ::position() method on an Fl_Window, inherited from Fl_Widget. I knew it was there, I knew it was inherited, but for the life of me I couldn't spot it in the docs.
In the bar.html (or is it baz? I was running out of names.), I would have clicked on "P", and then scanned down the list until I reached "position". Clicking on that entry brings me to Fl_Widget::position(), the inherited method.
I'll happily submit the script that generated this HTML hairball. The result ain't perfect, but it's a lot better than what's there now.
First though, someone should tell me what the file should be called, (I'm sure there are better choices than baz/bar.html) and I'll modify the script to 1. generate this file and 2. exclude it from the index operation to sidestep recursion. Someone should probably then add a link on documentation/index.html (really a table of contents) to whatever file you decide on.
As I mentioned, I don't grok HTML. When I look at other examples, I see a lot of comment-ish boilerplate at the front of the file. If this is at all needed, I can modify the script to generate it. | |
| |
| #7 | greg.ercolano
08:44 Jun 18, 2006 |
| Maybe the get_methods.pl file can be used to move forward on Mike's suggestion to use EMBED to attain the results of the suggested in matthais's Fl_Box.html example (as per the recent followups in fltk.development)
Assuming the Fl_*.html docs follow 'some kind of format' for all the methods, a perl script like the attached can quickly generate the methods links. | |
| |
| #8 | matt
23:35 Jun 18, 2006 |
| Would it make sense to create an application in the "test" directory that re-indexes our documentation? It would be an FLTK example showing how to create a simple UI for a tool that would normally be command line, and would go nicely with FLUID that creates parts of the distribution as well.
But, oh, wait, that exists and is called HTMLDoc ;-) | |
| |
| #9 | wilson.afn
07:48 Jun 19, 2006 |
| OK. I've played with HTMLdoc now and have two observations:
1. Mike needs to hire one of those Google consultants who raise page rank. I can't believe I didn't know about this. I searched again for "HTML indexer" and HTMLdoc was nowhere to be found in the first few pages. (Later, I got more specific and looked for "python html indexer" because it's the only language in which I am remotely capable of attempting such a feat.)
2. It is much more polished than lots of other stuff out there, but it doesn't quite do what I want.
Specifically, I had difficulty discovering if it would generate some form of index. My primary problem was due to the fact that htmldoc.html (which I think is the primary HTMLdoc doc) didn't have an index!
Fortunately, it was one giant file, and my browser could brute-force search for the string "index". The search reinforced my believe that although HTMLdoc can generate "Indexed HTML", it does not generate an index. | |
| |
| #10 | mike
08:40 Jun 19, 2006 |
| Actually, the latest 1.9 developer snapshot includes the index generator (finally!), so you'll be able to provide a file with a list of words/phrases and have them indexed through the whole manual.
FWIW, the format of the "words" file (which isn't documented yet... :) is:
word
phrase to index
[topic in index] word
[topic in index] phrase to index
So, for example, we could do:
[Widgets] Fl_Widget
[Widgets] Fl_Tabs
...
[Drawing Functions] fl_line
[Drawing Functions] fl_color
...
[Methods] value()
You can also list words and phrases multiple times under different topics to get them listed multiple times in the index... | |
| |
| #11 | matt
05:56 Aug 24, 2006 |
| Fixed in Subversion repository.
Thnaks for the suggestion and special thanks to Greg for his wonderful script. Adding a little vi magic (gosh, I *have* to learn Perl!) I was able to create an alphabetical index of all class method. I am pretty sure that this index is quite useful. I also added pretty much all fl_ functions to the documentation in a handy list. | |
[ Return to Bugs & Features ]
|
| |
