1. New Docs Online
- Posted by Jeremy Cowgar Jul 17, 2008
- 1362 views
I have put new docs online and importantly, at the bottom of every page it includes a "Last Published" field.
Jeremy
2. Re: New Docs Online
- Posted by jeremy (admin) Jul 24, 2008
- 1359 views
I have put new docs online and importantly, at the bottom of every page it includes a "Last Published" field.
docs are deployed again. Please take note of the changed navigation. I would like feedback. Thanks!
Jeremy
3. Re: New Docs Online
- Posted by DanM Jul 26, 2008
- 1337 views
I have put new docs online and importantly, at the bottom of every page it includes a "Last Published" field.
docs are deployed again. Please take note of the changed navigation. I would like feedback. Thanks!
Jeremy
Ok, here's mine:
1. The main title (in large black font),
"1 Euphoria Programming Language v4.0"
doesn't need the "1" in front of it, as it's an overall TITLE, and there's no number "2";
2. The next line,
"1 Euphoria Programming Language v4.0"
doesn't need (shouldn't have) "v4.0" at the end, because that SECTION is about Euphoria in general, not version 4.0 in particular;
3. Overall, from my perspective, it's too busy (ie, too much detail all at once, not enough simplified general categories leading to the details;
here's what I would suggest instead:
first, maybe some of the navigation stuff you have at the top, (though I don't really see its value at all)
then:
<title>Euphoria Programming Language v4.0
<first link> 1 Euphoria Programming Language
<second link> 2 Euphoria Reference Manual
<third link> 3 Mini-Guides
<forth link> 4 Language Reference
<fifth link> 5 Release Notes
each of these links would then jump to the appropriate section, whether it's a separate page or just down lower in the TOC page.
4. The "Language Reference" section is way too busy; I think it should rather look like this, stripped of all sub-sections (not including "notes", and of course, each item listed below would jump to the "Page Contents" section for that item):
4.1 Console
4.2 Data type conversion
4.3 Euphoria Database (EDS)
4.4 Date/Time
4.5 Dynamic Linking to C
4.6 Error Handling
4.7 File System
4.8 Input Routines (note: out of alphabetic order)
4.9 Graphics and Sound
4.10 Graphical Image Routines for DOS
4.11 Locale Routines
4.12 Map (hash table)
4.13 Math
4.14 Memory Management and other Machine Level routines
4.15 DOS low level routines (note: out of alphabetic order)
4.16 DOS low level routines (note: manual error, sb only one?)
4.17 Mouse
4.18 Windows Message Box (note: sb "Message Box (Windows)"?
4.19 Operating System Helpers
4.20 Pretty Printing
4.21 Prime Numbers
4.22 Regular Expressions
4.23 Searching
4.24 Sequence Manipulation
4.25 Sets
4.26 Internet Sockets(note: should be "Sockets (Internet)"?)
4.27 Sorting
4.28 Stack
4.29 Statistics
4.30 Multi-tasking (note: out of alphabetic order)
4.31 Text Manipulation
4.32 Extended Types (note: out of alphabetic order, or "Types (Extended?)
4.33 Unicode
4.34 Unit Testing Framework
4.35 Wildcard Matching
5. Within "Language Reference", clicking on any category, like "4.24 Sequence Manipulation" conveniently jumps to a page which has a nice TOC like layout, with a section titled "Page Contents"; it would, however, be nice and useful if each item listed in that top Page Contents section would have a short description (one line only) after it (like Rob did: "open - open a file or device") .
But in another respect, it's also too busy, with respect to all the sub-outline numbering preceding each individual item. The problem as I'm seeing it has three aspects:
- the presence of the sub-outline numbering in the first place. I understand the infrequent(?) utility of being able to reference someone to a section by that numbering, but I think the majority of the time people will be searching this section by item name, in which cases the numbering just visually interferes with seeing the item name(I don't mean you can't see the item name at all, just that it's made harder to easily & quickly see);
- the link "underlining" extends under both the outline numbering and the item name, causing it all to "blur together"; it would seem more easy to see and discern the word naming the item if those two (the outline numbering and the item name) were separated, with an underline under each, rather than one underline under both at the same time. Maybe even get rid of the underlining completely--it's not used in the higher levels of the doc, why here?
- the outline numbering and an item name are of the same size and weight; it would seem to help if the outline numbering for each item here were somewhat smaller, and the item name were in bold.
Dan M.
4. Re: New Docs Online (some feedback)
- Posted by DanM Aug 01, 2008
- 1264 views
I have put new docs online and importantly, at the bottom of every page it includes a "Last Published" field.
docs are deployed again. Please take note of the changed navigation. I would like feedback. Thanks!
Jeremy
Ok, here's mine:
1. The main title (in large black font),
"1 Euphoria Programming Language v4.0"
doesn't need the "1" in front of it, as it's an overall TITLE, and there's no number "2";
2. The next line,
"1 Euphoria Programming Language v4.0"
doesn't need (shouldn't have) "v4.0" at the end, because that SECTION is about Euphoria in general, not version 4.0 in particular;
3. Overall, from my perspective, it's too busy (ie, too much detail all at once, not enough simplified general categories leading to the details;
here's what I would suggest instead:
first, maybe some of the navigation stuff you have at the top, (though I don't really see its value at all)
then:
<title>Euphoria Programming Language v4.0
<first link> 1 Euphoria Programming Language
<second link> 2 Euphoria Reference Manual
<third link> 3 Mini-Guides
<forth link> 4 Language Reference
<fifth link> 5 Release Notes
each of these links would then jump to the appropriate section, whether it's a separate page or just down lower in the TOC page.
4. The "Language Reference" section is way too busy; I think it should rather look like this, stripped of all sub-sections (not including "notes", and of course, each item listed below would jump to the "Page Contents" section for that item):
4.1 Console
4.2 Data type conversion
4.3 Euphoria Database (EDS)
4.4 Date/Time
4.5 Dynamic Linking to C
4.6 Error Handling
4.7 File System
4.8 Input Routines (note: out of alphabetic order)
4.9 Graphics and Sound
4.10 Graphical Image Routines for DOS
4.11 Locale Routines
4.12 Map (hash table)
4.13 Math
4.14 Memory Management and other Machine Level routines
4.15 DOS low level routines (note: out of alphabetic order)
4.16 DOS low level routines (note: manual error, sb only one?)
4.17 Mouse
4.18 Windows Message Box (note: sb "Message Box (Windows)"?
4.19 Operating System Helpers
4.20 Pretty Printing
4.21 Prime Numbers
4.22 Regular Expressions
4.23 Searching
4.24 Sequence Manipulation
4.25 Sets
4.26 Internet Sockets(note: should be "Sockets (Internet)"?)
4.27 Sorting
4.28 Stack
4.29 Statistics
4.30 Multi-tasking (note: out of alphabetic order)
4.31 Text Manipulation
4.32 Extended Types (note: out of alphabetic order, or "Types (Extended?)
4.33 Unicode
4.34 Unit Testing Framework
4.35 Wildcard Matching
5. Within "Language Reference", clicking on any category, like "4.24 Sequence Manipulation" conveniently jumps to a page which has a nice TOC like layout, with a section titled "Page Contents"; it would, however, be nice and useful if each item listed in that top Page Contents section would have a short description (one line only) after it (like Rob did: "open - open a file or device") .
But in another respect, it's also too busy, with respect to all the sub-outline numbering preceding each individual item. The problem as I'm seeing it has three aspects:
- the presence of the sub-outline numbering in the first place. I understand the infrequent(?) utility of being able to reference someone to a section by that numbering, but I think the majority of the time people will be searching this section by item name, in which cases the numbering just visually interferes with seeing the item name(I don't mean you can't see the item name at all, just that it's made harder to easily & quickly see);
- the link "underlining" extends under both the outline numbering and the item name, causing it all to "blur together"; it would seem more easy to see and discern the word naming the item if those two (the outline numbering and the item name) were separated, with an underline under each, rather than one underline under both at the same time. Maybe even get rid of the underlining completely--it's not used in the higher levels of the doc, why here?
- the outline numbering and an item name are of the same size and weight; it would seem to help if the outline numbering for each item here were somewhat smaller, and the item name were in bold.
Dan M.
Comments?
DanM
5. Re: New Docs Online
- Posted by jeremy (admin) Aug 01, 2008
- 1271 views
1. The main title (in large black font),
"1 Euphoria Programming Language v4.0"
doesn't need the "1" in front of it, as it's an overall TITLE, and there's no number "2";
There should be 2, 3, 4 and 5. Soon there will be more.
2. The next line,
"1 Euphoria Programming Language v4.0"
doesn't need (shouldn't have) "v4.0" at the end, because that SECTION is about Euphoria in general, not version 4.0 in particular;
The whole document (in which that is the title) is reference for 4.0. As well, the general introduction will be changing to include a short section about all the new things in 4.0. But the 4.0 is needed to distinguish it from 3.x docs.
3. Overall, from my perspective, it's too busy (ie, too much detail all at once, not enough simplified general categories leading to the details;
here's what I would suggest instead:
first, maybe some of the navigation stuff you have at the top, (though I don't really see its value at all)
then:
<title>Euphoria Programming Language v4.0
<first link> 1 Euphoria Programming Language
<second link> 2 Euphoria Reference Manual
<third link> 3 Mini-Guides
<forth link> 4 Language Reference
<fifth link> 5 Release Notes
each of these links would then jump to the appropriate section, whether it's a separate page or just down lower in the TOC page.
Better navigation is needed. I am not sure how to fit all of that into the docs with out adding to the navigation complications. The navigation has changed since this message was posted. Is this still an issue for you?
4. The "Language Reference" section is way too busy; I think it should rather look like this, stripped of all sub-sections (not including "notes", and of course, each item listed below would jump to the "Page Contents" section for that item):
4.1 Console
4.2 Data type conversion
4.3 Euphoria Database (EDS)
4.4 Date/Time
<snip>
That is the only place where all functions are listed, many people use that page to do a Ctrl+F and start typing the function name they are looking for. That Toc is a section TOC and like any book, it will have much more detail. A technical text book will have a TOC at the front that lists major divisions, then when you go to an individual chapter, they will have a detailed chapter TOC. That is what you see on teach major section (chapter).
5. Within "Language Reference", clicking on any category, like "4.24 Sequence Manipulation" conveniently jumps to a page which has a nice TOC like layout, with a section titled "Page Contents"; it would, however, be nice and useful if each item listed in that top Page Contents section would have a short description (one line only) after it (like Rob did: "open - open a file or device") .
Yes, that would be nice, however we must realize that we have went from ~200 total functions to > 500 and by the time it's done I would say we will be over 600 functions. I am not yet sure how all this will work out.
Also, at this point in time it's a limitation of our document generation. When Rob was maintaining it, he had to manually create all TOC's. When he added a new function he had to change all reference numbers everywhere, he had to update index pages, he had to update the overview page, etc... There is no way we can maintain that manually with how rapidly things have been changing. Thus we are now all automated. Now, the problem with the automation is that a section title for book like material such as explaining a For loop is no different than a section title for the function split.
I have some ideas about how this could work, but then their is the idea of getting the short description from the inline docs also, that we moved to. (we maintain docs right with the functions now instead of having a separate place which leads to forgetfulness). The best thing I can come up with is take the short description as the first sentence in the description.
But in another respect, it's also too busy, with respect to all the sub-outline numbering preceding each individual item. The problem as I'm seeing it has three aspects:
- the presence of the sub-outline numbering in the first place. I understand the infrequent(?) utility of being able to reference someone to a section by that numbering, but I think the majority of the time people will be searching this section by item name, in which cases the numbering just visually interferes with seeing the item name(I don't mean you can't see the item name at all, just that it's made harder to easily & quickly see);
Bear in mind the docs will be available in PDF and .txt formats as well. I personally very much like the section numbering. It gives me reference. Most technical manuals (including the 3.x docs) have section numbering.
- the link "underlining" extends under both the outline numbering and the item name, causing it all to "blur together"; it would seem more easy to see and discern the word naming the item if those two (the outline numbering and the item name) were separated, with an underline under each, rather than one underline under both at the same time. Maybe even get rid of the underlining completely--it's not used in the higher levels of the doc, why here?
- the outline numbering and an item name are of the same size and weight; it would seem to help if the outline numbering for each item here were somewhat smaller, and the item name were in bold.
Underlining is pretty ugly. I have not styled the TOC sections yet, really. I will remove underlining from the TOC. I will also work further at making it easier to read. It's just not where my focus has been yet.
Thank you for your comments. This gives me some action points that I will address.
Jeremy
6. Re: New Docs Online (sub-thread: is doc gen code available?)
- Posted by DanM Aug 05, 2008
- 1247 views
1. The main title (in large black font),
"1 Euphoria Programming Language v4.0"
doesn't need the "1" in front of it, as it's an overall TITLE, and there's no number "2";
There should be 2, 3, 4 and 5. Soon there will be more.
Sorry, guess I wasn't clear: I'm not talking about the five numbered sections, for which there will be more in the future, ie:
1 Euphoria Programming Language v4.0
2 Euphoria Reference Manual
3 Mini-Guides
4 Language Reference
5 Release Notes
I see them. I'm not referring to the first item in the above list, but rather to the actual main title, the line just under:
Previous Chapter: None Previous: None Up: 1 Euphoria Programming Language v4.0 Next: 1.1 Introduction Next Chapter: 2 Euphoria Reference Manual
that is, the TITLE of the doc; that's the line that doesn't seem to need the "1" in front of it, since there would only be one title for the doc, therefore no need to identify it as list item #1.
2. The next line,
"1 Euphoria Programming Language v4.0"
doesn't need (shouldn't have) "v4.0" at the end, because that SECTION is about Euphoria in general, not version 4.0 in particular;
The whole document (in which that is the title) is reference for 4.0. As well, the general introduction will be changing to include a short section about all the new things in 4.0. But the 4.0 is needed to distinguish it from 3.x docs.
See above comment: I'm not talking in this instance about the title. Of course you're correct that the title either needs or can very much benefit from indicating that this doc is for v4.0; but that's not the line in the doc I'm referring to, it's the second line which again says
"1 Euphoria Programming Language v4.0"
but in a smaller font, and is (currently) the first section of 5 sections, that I'm suggesting doesn't need the "v4.0" after it; after all, none of the other similarly numbered sections include it. Again, that section is just about Euphoria in general, at least for the most part.
3. Overall, from my perspective, it's too busy (ie, too much detail all at once, not enough simplified general categories leading to the details;
here's what I would suggest instead:
first, maybe some of the navigation stuff you have at the top, (though I don't really see its value at all)
then:
<title>Euphoria Programming Language v4.0
<first link> 1 Euphoria Programming Language
<second link> 2 Euphoria Reference Manual
<third link> 3 Mini-Guides
<forth link> 4 Language Reference
<fifth link> 5 Release Notes
each of these links would then jump to the appropriate section, whether it's a separate page or just down lower in the TOC page.
Better navigation is needed. I am not sure how to fit all of that into the docs with out adding to the navigation complications. The navigation has changed since this message was posted. Is this still an issue for you?
I'm not entirely sure. I can't recall if the earlier version of the doc had underlining under all the items on the main page or not; if it did, and you removed them, then that helps, although it's not my main concern on that page. I'd like to see a condensed TOC, where the 5 (or more) main sections are just listed by name/link, so navigation would just be a matter of clicking on the desired section name, and then (specifically for Language Reference), on the desired routine category.
However, if this is very much not what you want for the doc, I wonder if you could let me try to work on a variant of the doc generating program, to see if I could make it output as I'd like? I'd much rather not have to deal with SVN (old dogs not like to have to learn new tricks), and I'd need some version or portion of Euphoria 4.0 to run it against. Of course, if I try to do this, it will take me at least forever and a day! 
4. The "Language Reference" section is way too busy; I think it should rather look like this, stripped of all sub-sections (not including "notes", and of course, each item listed below would jump to the "Page Contents" section for that item):
4.1 Console
4.2 Data type conversion
4.3 Euphoria Database (EDS)
4.4 Date/Time
<snip>
That is the only place where all functions are listed, many people use that page to do a Ctrl+F and start typing the function name they are looking for. That Toc is a section TOC and like any book, it will have much more detail. A technical text book will have a TOC at the front that lists major divisions, then when you go to an individual chapter, they will have a detailed chapter TOC. That is what you see on teach major section (chapter).
Ok, I think I understand, but when I'm looking for a function, it's often the name I can't remember, so I start looking for the general category, and then read down a list of them, so I can recognize it when I see it. Different strokes. 
5. Within "Language Reference", clicking on any category, like "4.24 Sequence Manipulation" conveniently jumps to a page which has a nice TOC like layout, with a section titled "Page Contents"; it would, however, be nice and useful if each item listed in that top Page Contents section would have a short description (one line only) after it (like Rob did: "open - open a file or device") .
Yes, that would be nice, however we must realize that we have went from ~200 total functions to > 500 and by the time it's done I would say we will be over 600 functions. I am not yet sure how all this will work out.
Also, at this point in time it's a limitation of our document generation. When Rob was maintaining it, he had to manually create all TOC's. When he added a new function he had to change all reference numbers everywhere, he had to update index pages, he had to update the overview page, etc... There is no way we can maintain that manually with how rapidly things have been changing. Thus we are now all automated. Now, the problem with the automation is that a section title for book like material such as explaining a For loop is no different than a section title for the function split.
I have some ideas about how this could work, but then their is the idea of getting the short description from the inline docs also, that we moved to. (we maintain docs right with the functions now instead of having a separate place which leads to forgetfulness). The best thing I can come up with is take the short description as the first sentence in the description.
Yes, using the short description that's inline with the function(s) themselves, as the short description in the line with the name of the function in the docs, that's what I mean.
But in another respect, it's also too busy, with respect to all the sub-outline numbering preceding each individual item. The problem as I'm seeing it has three aspects:
- the presence of the sub-outline numbering in the first place. I understand the infrequent(?) utility of being able to reference someone to a section by that numbering, but I think the majority of the time people will be searching this section by item name, in which cases the numbering just visually interferes with seeing the item name(I don't mean you can't see the item name at all, just that it's made harder to easily & quickly see);
Bear in mind the docs will be available in PDF and .txt formats as well. I personally very much like the section numbering. It gives me reference. Most technical manuals (including the 3.x docs) have section numbering.
Well, actually the 3.x docs don't carry the sub-section numbering down to the same degree. 3.x has SECTION numbering, but not sub section numbering. "2.9", but not "2.9.4.1"
I can understand that the sub-section numbering can be useful for referring people to, but just reading the doc, all those numbers tend, for me, to be unnecesarily distractive. It's the names of the routines I'm interested in seeing, not the sub-section numbering. Not asking you to remove them, just maybe make (or wait forever for me to make?) an alternative view that is "condensed". Could have a button at top of TOC that says, "Condensed View of TOC", perhaps?
- the link "underlining" extends under both the outline numbering and the item name, causing it all to "blur together"; it would seem more easy to see and discern the word naming the item if those two (the outline numbering and the item name) were separated, with an underline under each, rather than one underline under both at the same time. Maybe even get rid of the underlining completely--it's not used in the higher levels of the doc, why here?
- the outline numbering and an item name are of the same size and weight; it would seem to help if the outline numbering for each item here were somewhat smaller, and the item name were in bold.
Underlining is pretty ugly. I have not styled the TOC sections yet, really. I will remove underlining from the TOC. I will also work further at making it easier to read. It's just not where my focus has been yet.
Understood. And thanks for all your (& all you'se all's) efforts to expand/improve Euphoria
Thank you for your comments. This gives me some action points that I will address.
Jeremy
Dan M.
7. Re: New Docs Online (sub-thread: is doc gen code available?)
- Posted by jeremy (admin) Aug 05, 2008
- 1223 views
Previous Chapter: None Previous: None Up: 1 Euphoria Programming Language v4.0 Next: 1.1 Introduction Next Chapter: 2 Euphoria Reference Manual
That will change as you navigate through the document. Say for instance, you are on a sub chapter, "2. Euphoria Reference Manual"... The "Up:" Link will read "2. Euphoria Reference Manual".
See above comment: I'm not talking in this instance about the title. Of course you're correct that the title either needs or can very much benefit from indicating that this doc is for v4.0; but that's not the line in the doc I'm referring to, it's the second line which again says
"1 Euphoria Programming Language v4.0"
but in a smaller font, and is (currently) the first section of 5 sections, that I'm suggesting doesn't need the "v4.0" after it; after all, none of the other similarly numbered sections include it. Again, that section is just about Euphoria in general, at least for the most part.
I personally like how it lets you know where you are at in the documentation. If it did not say the 1., 2., 3., then I may not know when browsing how many sections back or forward I could go.
I'm not entirely sure. I can't recall if the earlier version of the doc had underlining under all the items on the main page or not; if it did, and you removed them, then that helps, although it's not my main concern on that page. I'd like to see a condensed TOC, where the 5 (or more) main sections are just listed by name/link, so navigation would just be a matter of clicking on the desired section name, and then (specifically for Language Reference), on the desired routine category.
However, if this is very much not what you want for the doc, I wonder if you could let me try to work on a variant of the doc generating program, to see if I could make it output as I'd like? I'd much rather not have to deal with SVN (old dogs not like to have to learn new tricks), and I'd need some version or portion of Euphoria 4.0 to run it against. Of course, if I try to do this, it will take me at least forever and a day!
SVN is how the entire system is managed. It becomes quite cumbersome to accept patches that are not diffs from the latest SVN. SVN is really a tool that is vital to groups of people working on the same code. It's really not hard at all to pick up.
The doc generation program has had many weeks of development and still a few weeks left. It's currently about 6500 lines of tedious code to get everything parsed correctly. It's not a trivial application as one might think. I'm not saying you can't give it a try, but I am saying that hours of internal discussions went on and many, many, many hours went into making the tools to do the job, then debugging, refining, debugging, refining, adding new parsing, etc... Further, the tool has the capability of being 100% generic, i.e. it will not only work with anyone's project but it has plugable parsers and will work with C, Java, PHP, Ruby, Tcl, Perl, etc... source just fine.
Well, actually the 3.x docs don't carry the sub-section numbering down to the same degree. 3.x has SECTION numbering, but not sub section numbering. "2.9", but not "2.9.4.1"
Yes, it does not take it down to the function level, which I think is needed.
I can understand that the sub-section numbering can be useful for referring people to, but just reading the doc, all those numbers tend, for me, to be unnecesarily distractive. It's the names of the routines I'm interested in seeing, not the sub-section numbering. Not asking you to remove them, just maybe make (or wait forever for me to make?) an alternative view that is "condensed". Could have a button at top of TOC that says, "Condensed View of TOC", perhaps?
I picked up a few of my programming books sitting on the desk and the TOC seems to be in line with those books. One book does have on the back cover a chapter list, which would be what you are looking for.
The doc tools are available but still under development, you can get them:
svn co http://jeremy.cowgar.com/svn/eudoc/trunk eudoc cd eudoc svn co http://jeremy.cowgar.com/svn/creole/trunk creole
In the eudoc directory you will then find a build.bat and build.sh that you can run on your platform (Windows, DOS, Linux, FreeBSD or OSX whatever it may be).
Jeremy
8. Re: New Docs Online (sub-thread: is doc gen code available?)
- Posted by DanM Aug 05, 2008
- 1268 views
Previous Chapter: None Previous: None Up: 1 Euphoria Programming Language v4.0 Next: 1.1 Introduction Next Chapter: 2 Euphoria Reference Manual
That will change as you navigate through the document. Say for instance, you are on a sub chapter, "2. Euphoria Reference Manual"... The "Up:" Link will read "2. Euphoria Reference Manual".
Huh?? Not sure why you're explaining that, although it seems like an interesting idea. I wasn't commenting at all about the above, I was just using the above as a line-by-line reference to what comes after it in the docs, namely, the first, BIG (large font) line which reads:
1 Euphoria Programming Language v4.0
that's the line that I'm saying doesn't need the "1" in front of it, since it's the singular TITLE of the whole documentation. Note that I'm not saying that the next line, which looks exactly the same except it's in smaller font, shouldn't have "1" in front of it, as it is "one of many", ie, the first section of 5 (currently) sections. But the TITLE line (that is, just below the navigation panel you mention above), the DOC TITLE line, is the one that I'm suggesting shouldn't have "1" in front of it as it is the TITLE, not a section.
To use your textbook analogy, it's like a textbook being titled:
"1 How To Design Computer Programs", instead of:
""How To Design Computer Programs".
What's the point of the "1" in the title?
See above comment: I'm not talking in this instance about the title. Of course you're correct that the title either needs or can very much benefit from indicating that this doc is for v4.0; but that's not the line in the doc I'm referring to, it's the second line which again says
"1 Euphoria Programming Language v4.0"
but in a smaller font, and is (currently) the first section of 5 sections, that I'm suggesting doesn't need the "v4.0" after it; after all, none of the other similarly numbered sections include it. Again, that section is just about Euphoria in general, at least for the most part.
I personally like how it lets you know where you are at in the documentation. If it did not say the 1., 2., 3., then I may not know when browsing how many sections back or forward I could go.
Huh?? Here I'm also confused by what you've said, because I didn't in any way suggest to take away the 1.,2.,3.,... from the section names!
What I was trying to say was that since the DOC TITLE already indicates that this doc is about Euphoria v4.0, (as is entirely reasonable), then the first section of that doc, which is just about Euphoria in general, ought just to be:
1 Euphoria Programming Language
without the "v 4.0", just like all the other sections in the doc after that section.
I know these issues aren't very important, and I really have no strong objection to however you do it; some are just things I noticed that I thought I'd pass along, while others would, I think, help me and perhaps others read the manual easier. But it seems from your responses above that you're not getting what I'm trying to point out at all. Maybe I put too many suggestions/observations into one thread?? Should I have made individual posts for each observation/suggestion?
I'm not entirely sure. I can't recall if the earlier version of the doc had underlining under all the items on the main page or not; if it did, and you removed them, then that helps, although it's not my main concern on that page. I'd like to see a condensed TOC, where the 5 (or more) main sections are just listed by name/link, so navigation would just be a matter of clicking on the desired section name, and then (specifically for Language Reference), on the desired routine category.
However, if this is very much not what you want for the doc, I wonder if you could let me try to work on a variant of the doc generating program, to see if I could make it output as I'd like? I'd much rather not have to deal with SVN (old dogs not like to have to learn new tricks), and I'd need some version or portion of Euphoria 4.0 to run it against. Of course, if I try to do this, it will take me at least forever and a day!
SVN is how the entire system is managed. It becomes quite cumbersome to accept patches that are not diffs from the latest SVN. SVN is really a tool that is vital to groups of people working on the same code. It's really not hard at all to pick up.
The doc generation program has had many weeks of development and still a few weeks left. It's currently about 6500 lines of tedious code to get everything parsed correctly. It's not a trivial application as one might think. I'm not saying you can't give it a try, but I am saying that hours of internal discussions went on and many, many, many hours went into making the tools to do the job, then debugging, refining, debugging, refining, adding new parsing, etc... Further, the tool has the capability of being 100% generic, i.e. it will not only work with anyone's project but it has plugable parsers and will work with C, Java, PHP, Ruby, Tcl, Perl, etc... source just fine.
Ok, I'll leave it alone, but I'm still wondering if it's not possible to have the doc gen pgm spit out some alternative pages, whose format I'll try to re-describe later, which could be accessed by the reader clicking on a button up in your navigation panel, labeled something like, "Short Form TOC", or something??
Well, actually the 3.x docs don't carry the sub-section numbering down to the same degree. 3.x has SECTION numbering, but not sub section numbering. "2.9", but not "2.9.4.1"
Yes, it does not take it down to the function level, which I think is needed.
Yes, I understand, & I'm not asking that they be eliminated, just that an alternative set of pages be accessable which don't have them.
I can understand that the sub-section numbering can be useful for referring people to, but just reading the doc, all those numbers tend, for me, to be unnecesarily distractive. It's the names of the routines I'm interested in seeing, not the sub-section numbering. Not asking you to remove them, just maybe make (or wait forever for me to make?) an alternative view that is "condensed". Could have a button at top of TOC that says, "Condensed View of TOC", perhaps?
I picked up a few of my programming books sitting on the desk and the TOC seems to be in line with those books. One book does have on the back cover a chapter list, which would be what you are looking for.
Yes, I'm envisioning that such a chapter list would be an alternive navigation method. Click on a chapter, open it up; click on a section in the chapter, open it up.
The doc tools are available but still under development, you can get them:
svn co http://jeremy.cowgar.com/svn/eudoc/trunk eudoc cd eudoc svn co http://jeremy.cowgar.com/svn/creole/trunk creole
In the eudoc directory you will then find a build.bat and build.sh that you can run on your platform (Windows, DOS, Linux, FreeBSD or OSX whatever it may be).
Jeremy
I wonder if, alternativly, I could get the latest html source of the doc, so I could just edit that to show you what I mean? That might be simpler all around. (I'd try to copy it from viewing the source, but every time I try to do that, for some reason a Euphoria program, "NPad" comes up, which has nothing to do with the manual, it happens whenever I try to view any html source, don't know why).
Dan
9. Re: New Docs Online (sub-thread: is doc gen code available?)
- Posted by mattlewis (admin) Aug 05, 2008
- 1273 views
I wonder if, alternativly, I could get the latest html source of the doc, so I could just edit that to show you what I mean? That might be simpler all around. (I'd try to copy it from viewing the source, but every time I try to do that, for some reason a Euphoria program, "NPad" comes up, which has nothing to do with the manual, it happens whenever I try to view any html source, don't know why).
If you're using IE, then somehow, it was configured to be the default html source editor. See:
http://dotnet.org.za/thea/archive/2004/11/25/7933.aspx or http://lists.evolt.org/archive/Week-of-Mon-20030526/141670.html
...for more info.
Matt
10. Re: New Docs Online (sub-thread: is doc gen code available?)
- Posted by jeremy (admin) Aug 05, 2008
- 1243 views
I wonder if, alternativly, I could get the latest html source of the doc, so I could just edit that to show you what I mean? That might be simpler all around. (I'd try to copy it from viewing the source, but every time I try to do that, for some reason a Euphoria program, "NPad" comes up, which has nothing to do with the manual, it happens whenever I try to view any html source, don't know why).
Sorry to be so slow at catching on to this. I'm not meaning to create additional work. I think I finally understand what you mean about the 1 Euphoria... You are talking about the big bold one on top of the Table of Contents? That is the section title, not really a book title. If you go:
http://openeuphoria.org/docs/eu400_0009.html
You will see it for 2 Euphoria Reference Manual. It's the chapter title. It just so happens that the 1st chapter contains a table of contents. That would really go in front matter on a book, but we do not yet have the concept of Front Matter, I do not think, in the docs. I could probably play with it for a little bit and see if I could create front matter.
Jeremy
11. Re: New Docs Online (sub-thread: is doc gen code available?)
- Posted by DanM Aug 05, 2008
- 1238 views
I wonder if, alternativly, I could get the latest html source of the doc, so I could just edit that to show you what I mean? That might be simpler all around. (I'd try to copy it from viewing the source, but every time I try to do that, for some reason a Euphoria program, "NPad" comes up, which has nothing to do with the manual, it happens whenever I try to view any html source, don't know why).
Sorry to be so slow at catching on to this. I'm not meaning to create additional work. I think I finally understand what you mean about the 1 Euphoria... You are talking about the big bold one on top of the Table of Contents? That is the section title, not really a book title. If you go:
http://openeuphoria.org/docs/eu400_0009.html
You will see it for 2 Euphoria Reference Manual. It's the chapter title. It just so happens that the 1st chapter contains a table of contents. That would really go in front matter on a book, but we do not yet have the concept of Front Matter, I do not think, in the docs. I could probably play with it for a little bit and see if I could create front matter.
Jeremy
OH! !
Well now I see why you didn't understand what I was trying to say! It looked like a doc title ("front matter"?) to me, since it was in bold, and the next line was the same thing, though in a smaller font size, and then if you scroll down (rather than use your navigation thingys), there's a second section name in the same smaller font weight as the first, etc, all of which made that first big bold line look (to me, anyway!) like a title! !
And that's what I've been talking about as being a title, and that's why you thought I was advocating removing the section numbering from the sections! Talk about talking past one another! I'm just glad you figured it out!
But I certainly would think that the first chapter shouldn't contain the TOC for the whole document, right? That's worse than recursive, it's downright arcane!
Dan
12. Re: New Docs Online (sub-thread: is doc gen code available?)
- Posted by jeremy (admin) Aug 12, 2008
- 1239 views
Docs have been updated again. Not all problems solved, but quite a few.
Jeremy
