OpenEuphoria

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

4. Re: Another round of docs

• Posted by Jeremy Cowgar Jul 05, 2008
• 941 views

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

6. Re: Another round of docs

• Posted by Dan M. Jul 05, 2008
• 959 views
• Last edited Jul 06, 2008

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 

4.5.4 File name parsing 
 pathinfo 
 dirname 
 filename 
 filebase 
 fileext 

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