1. Another round of docs
- Posted by Jeremy Cowgar Jul 05, 2008
- 968 views
http://jeremy.cowgar.com/euphoria/eu400_0002.html
Still many issues but we are working on them. Styling as well. Chris Covier is going through the includes and adding Parameters and Returns blocks to all functions as well.
Jeremy
2. Re: Another round of docs
- Posted by Dan M. Jul 05, 2008
- 1017 views
I like it! You found/created a nice, intuitive way to have both a long list of routines etc with their "long" descriptions, AND have just a list of routine names which then jump to the long descriptions. Congrats!
I wonder though, if when you get to a "Page Contents", if each of the list of items under the main divisions on such a page really need the full outline sequence of numbers in front of them?
What I mean is, instead of:
4.5.4 File name parsing
4.5.4.1 pathinfo
4.5.4.2 dirname
4.5.4.3 filename
4.5.4.4 filebase
4.5.4.5 fileext
just have:
4.5.4 File name parsing
pathinfo
dirname
filename
filebase
fileext
since each of the items listed won't have any sub items under them.
Reason would be that the sub-numbers don't really add any information value, and sorta obscure the name of the item of interest with the repeated numbers.
Dan
3. Re: Another round of docs
- Posted by Dan M. Jul 05, 2008
- 933 views
I did mean to carry over the original indentations, the post just didn't show my leading spaces; I meant it to show as:
4.5.4 File name parsing pathinfo dirname filename filebase fileext
if I did it right this time. When you have time "preview" would really help!
Dan
4. Re: Another round of docs
- Posted by Jeremy Cowgar Jul 05, 2008
- 941 views
I did mean to carry over the original indentations, the post just didn't show my leading spaces; I meant it to show as:
4.5.4 File name parsing pathinfo dirname filename filebase fileext
I'd have to see it in place. I am not sure how trivial that would be to implement. The way the docs are created is a new tool called eudoc. It reads a list of files either by command line or by an assembly file. It has plugable parsers to handle different file types. For instance, .txt files are are simply read and output as is, they are considered to be in creole format already. Any euphoria source file is passed to the euparser, which reads docs from comments and reads source to find exported/global items, it then outputs in creole format. Other parsers could be added, for instance, C, Python, Ruby or any language. I am planning on having a generic parser where you simply tell it what the language comment characters are and it'll do the rest.
Anyway, once all files are collected, it writes out one file from all the sources. That file is in the wikipedia:Creole format. We can then use any tool that reads a creole file. Numerous ones exist but IMHO, none as nice as the one that Derek has been able to create, which is of course written in Euphoria also. Derek's tool has many additions for publishing Creole files such as we have, including the Table of Contents, File Splitting, inner document links and much more.
I said all that to say, I am not sure what Derek would have to change. As the output tool is what actually is responsible for the Table of Contents and section numbering. I do have the ability to turn numbering on and off for any level, but it's a global option and I think it's good for them to have section numbers. i.e., Dan, see section 2.4.3 for XYZ. Hm, thinking about this, I think it would be easy for him to add a <span class="section_numbering">...</span> around the numbers, then we could make it a smaller font or something. That might do it and be easy to implement?
Jeremy
5. Re: Another round of docs
- Posted by Dan M. Jul 05, 2008
- 943 views
I did mean to carry over the original indentations, the post just didn't show my leading spaces; I meant it to show as:
4.5.4 File name parsing pathinfo dirname filename filebase fileext
I'd have to see it in place. I am not sure how trivial that would be to implement. The way the docs are created is a new tool called eudoc. It reads a list of files either by command line or by an assembly file. It has plugable parsers to handle different file types. For instance, .txt files are are simply read and output as is, they are considered to be in creole format already. Any euphoria source file is passed to the euparser, which reads docs from comments and reads source to find exported/global items, it then outputs in creole format. Other parsers could be added, for instance, C, Python, Ruby or any language. I am planning on having a generic parser where you simply tell it what the language comment characters are and it'll do the rest.
Anyway, once all files are collected, it writes out one file from all the sources. That file is in the wikipedia:Creole format. We can then use any tool that reads a creole file. Numerous ones exist but IMHO, none as nice as the one that Derek has been able to create, which is of course written in Euphoria also. Derek's tool has many additions for publishing Creole files such as we have, including the Table of Contents, File Splitting, inner document links and much more.
I said all that to say, I am not sure what Derek would have to change. As the output tool is what actually is responsible for the Table of Contents and section numbering. I do have the ability to turn numbering on and off for any level, but it's a global option and I think it's good for them to have section numbers. i.e., Dan, see section 2.4.3 for XYZ. Hm, thinking about this, I think it would be easy for him to add a <span class="section_numbering">...</span> around the numbers, then we could make it a smaller font or something. That might do it and be easy to implement?
Jeremy
Hmm...what I'm thinking is make it retain the numbering if you click on
4.5.4 File name parsing
but not show the sub numbering if you click on
4.5 File System
that way, you could make reference to a sub-section, and those numbers would exist, in the "main" part of the doc, so a person could go to a specified sub-section; but in the "alternative" part of the doc that has the "Page Contents" listings, those sub-section numbering wouldn't show and wouldn't be necessary?
Dan
6. Re: Another round of docs
- Posted by Dan M. Jul 05, 2008
- 959 views
- Last edited Jul 06, 2008
I like it! You found/created a nice, intuitive way to have both a long list of routines etc with their "long" descriptions, AND have just a list of routine names which then jump to the long descriptions. Congrats!
I wonder though, if when you get to a "Page Contents", if each of the list of items under the main divisions on such a page really need the full outline sequence of numbers in front of them?
What I mean is, instead of:
4.5.4 File name parsing 4.5.4.1 pathinfo 4.5.4.2 dirname 4.5.4.3 filename 4.5.4.4 filebase 4.5.4.5 fileext
just have:
4.5.4 File name parsing pathinfo dirname filename filebase fileext
since each of the items listed won't have any sub items under them.
Reason would be that the sub-numbers don't really add any information value, and sorta obscure the name of the item of interest with the repeated numbers.
Dan
Oops, I didn't notice that the short description that I'd like presented with the "list" of routines presented on the "Page Contents" page accessed by clicking on any of the sub-categories of the main categories under "Language Reference" (such as: "File System") are missing.
What I mean is, if you follow the above sequenc of clicking:
(go down to "Language Reference", and click directly on "File System", then scroll down to "File name parsing"), if you all can see your way to change/add it, I'd like to see:
4.5.4 File name parsing pathinfo Parse a fully qualified pathname. dirname Return the directory name of a fully qualified filename filename Return the file name portion of a fully qualified filename filebase Return the base filename of path fileext Return the file extension of a fully qualified filename
That's probably not the best example, but I already had it in place, so I used it.
What do you think?
Dan
7. Re: Another round of docs
- Posted by Jeremy Cowgar Jul 05, 2008
- 980 views
- Last edited Jul 06, 2008
4.5.4 File name parsing pathinfo Parse a fully qualified pathname. dirname Return the directory name of a fully qualified filename filename Return the file name portion of a fully qualified filename filebase Return the base filename of path fileext Return the file extension of a fully qualified filename
I think it's a good idea, just not sure how to automate it yet, but will talk it over with Derek.
Jeremy