1. Euphoria 4.0 docs
- Posted by Jerry_Story Aug 08, 2010
- 1623 views
Is there a plan to put everything in Euphoria 4.0 docs in alphabetic order so it's easier to find? That would be better than looking thru the whole document just to find one little thing.
2. Re: Euphoria 4.0 docs
- Posted by _tom (admin) Aug 09, 2010
- 1521 views
Creating docs
Documentation is created from text that is part of the Euphoria source-code. That means the topics are ordered based on how the source-code itself is written.
Two Euphoria programs do the work, eudoc extracts the text, and creolehtml produces an html product.
This makes creating the documentation (automatically) easy.
Alternative ideas?
- do you want an alternative copy of the docs with each heading sorted into one large alphabetic document?
- would an alphabetic contents for each chapter help?
- can you suggest a completely different look?
3. Re: Euphoria 4.0 docs
- Posted by Jerry_Story Aug 09, 2010
- 1453 views
Alphabetical order of everything in one file or one chapter would be a great help in looking things up. Sometimes it is necessary to look up some little detail such as spelling or which file to include or arguments, and the way the docs are now I need to go thru half of the whole document to find this little detail.
4. Re: Euphoria 4.0 docs
- Posted by petelomax Aug 10, 2010
- 1473 views
This makes creating the documentation (automatically) easy.
I have no words
5. Re: Euphoria 4.0 docs
- Posted by DerekParnell (admin) Aug 10, 2010
- 1436 views
Is there a plan to put everything in Euphoria 4.0 docs in alphabetic order so it's easier to find? That would be better than looking thru the whole document just to find one little thing.
I'm currently working to enhance the automatic HTML generation by creating an alphabetical index of headings and public/global symbols (eg. library routines), plus creating an type of 'KWIC' index.
6. Re: Euphoria 4.0 docs
- Posted by mattlewis (admin) Aug 10, 2010
- 1393 views
This makes creating the documentation (automatically) easy.
I have no words
It's actually pretty simple, once you have the environment set up. Basically, need to build eudoc and creolehtml (these are in the Euphoria svn repository) and put them in your path. You'll also need euphoria v4 installed. On Windows, you'll need Watcom, other platforms require GNU make. Then the makefile takes care of the rest:
*nix: $ ./configure $ make htmldoc $ make pdfdoc Windows: > configure.bat > wmake htmldoc > wmake pdfdoc
Matt
7. Re: Euphoria 4.0 docs
- Posted by jimcbrown (admin) Aug 10, 2010
- 1412 views
This makes creating the documentation (automatically) easy.
I have no words
It's actually pretty simple
Unless you're the coder that's writing those annoying documentation comments - er, "coding".
8. Re: Euphoria 4.0 docs
- Posted by mattlewis (admin) Aug 10, 2010
- 1434 views
This makes creating the documentation (automatically) easy.
I have no words
It's actually pretty simple
Unless you're the coder that's writing those annoying documentation comments - er, "coding".
Yes, I try very hard not to be that guy. 
Matt
9. Re: Euphoria 4.0 docs
- Posted by useless Aug 10, 2010
- 1492 views
and then once the html is done, can whoever does the pdf fix the scene in
http://designerthinking.com/images/split_any().jpg
because whatever no_empty is, it's not showing. And in section 11.4.5.12, replace, <built-in> function replace(... can't tell what stop is.
There's more, but this illustrates the problem.
useless
10. Re: Euphoria 4.0 docs
- Posted by DanM Aug 10, 2010
- 1443 views
Creating docs
Documentation is created from text that is part of the Euphoria source-code. That means the topics are ordered based on how the source-code itself is written.
Two Euphoria programs do the work, eudoc extracts the text, and creolehtml produces an html product.
This makes creating the documentation (automatically) easy.
Alternative ideas?
- do you want an alternative copy of the docs with each heading sorted into one large alphabetic document?
- would an alphabetic contents for each chapter help?
- can you suggest a completely different look?
As I've suggested before, make a SHORT page, (could be an ALTERNATIVE page that user could go to instead of the "main" first page), that has just the current CHAPTER HEADINGS, probably in the same order, and perhaps a MINIMUM of 2nd level items, so that a user can more quickly see at a glance where to go to to get the information they want, rather than the current LONG page with S-O-O-O much on it that one has to scroll down and down and down in order to see all that's there. Again, this could be an ADDITIONAL page, working WITH the existing first page of the doc as an ALTERNATIVE, not necessarily a REPLACEMENT.
Of course, an alphabetic index is useful/necessary too.
Dan M.
11. Re: Euphoria 4.0 docs
- Posted by _tom (admin) Aug 10, 2010
- 1384 views
Kat, I appreciate your comments on the documentation. I see that some lines are truncated. As a "consolation," notice that the missing information is repeated under the heading Parameters: (But it does need fixing.)
A question for Derek, would a wordwrap option in creolehtml to fix this be an easy fix? If not, I could experiment with post processing of the html that goes into the pdf maker.
Creole is an excellent Wiki markup, and good for marking the documentation. It is not a "desktop publisher," which means no fine control of how the pdf looks. If someone knows how to convert html to pdf (other than the htmldoc program) I would be interested in learning how to do it.
An "alphabetized documentation version" it is an interesting idea. So far my efforts to create one have been a big mess. I will keep trying.
Dan, I have previously tried a few variations using your ideas. I did this by writing a few utilities that would rewrite the html before the docs got converted to pdf. The result was that creating documentation became very convoluted. Probably mostly due to my lack of programming skills, and partially due to htmldoc not letting me think in terms of desktop publishing. I admit that I got lazy when I put the last pdf up at RapidEuphoria, using just default settings for everything.
--
I just melted down my computer--beware of Foxconn. When I win the lottery I will get a new computer. This is to say sorry in advance for the slow progress in improving the documentation.
--
"I have no words"
This goes nicely with (automatically) easy, which is a symptom of my reaction to a dead computer. My math professor would torture us with "it's intuitively obvious."
12. Re: Euphoria 4.0 docs
- Posted by DanM Aug 10, 2010
- 1379 views
<snip>
Dan, I have previously tried a few variations using your ideas. I did this by writing a few utilities that would rewrite the html before the docs got converted to pdf. The result was that creating documentation became very convoluted. Probably mostly due to my lack of programming skills, and partially due to htmldoc not letting me think in terms of desktop publishing. I admit that I got lazy when I put the last pdf up at RapidEuphoria, using just default settings for everything.
--
I just melted down my computer--beware of Foxconn. When I win the lottery I will get a new computer. This is to say sorry in advance for the slow progress in improving the documentation.
--
"I have no words"
This goes nicely with (automatically) easy, which is a symptom of my reaction to a dead computer. My math professor would torture us with "it's intuitively obvious."
I remember working a little bit, quite a while ago, for some reason, on a MUCH earlier version of makedoc, so I have a vague, fuzzy sense of how *it* worked; so I'd wonder, since eudoc similarly extracts the text from the source code, couldn't you "just" hold the major "chapter" headings, and their next level items, as they're extracted, and then use that data to create an alternate page based on those, with a link to it from the main page?
Dan
13. Re: Euphoria 4.0 docs
- Posted by useless Aug 10, 2010
- 1357 views
I am glad to have the pdf in existance, i tend to use it more than the .txt of the extracted documentation, just because it's sooooo easier to search. And i hurt myself typing that because i hate pdfs.
Dan, do you have an example of what you want the help file to look like?
useless
14. Re: Euphoria 4.0 docs
- Posted by DanM Aug 10, 2010
- 1376 views
I am glad to have the pdf in existance, i tend to use it more than the .txt of the extracted documentation, just because it's sooooo easier to search. And i hurt myself typing that because i hate pdfs.
Dan, do you have an example of what you want the help file to look like?
useless
I'll see if I can put one together in a little while, I know I did that once before, maybe I can find it here! 
Dan
15. Re: Euphoria 4.0 docs
- Posted by DerekParnell (admin) Aug 10, 2010
- 1438 views
... couldn't you "just" hold the major "chapter" headings, and their next level items, as they're extracted, and then use that data to create an alternate page based on those, with a link to it from the main page?
I think that's what I said I was working on. An option in eudoc will be to create index files and these will have entries be sorted by name sequence, which point back to items in the main html doc files.
On each main file there will be a link to the top-level index file.
Also, there will be a 'keyword in context' set of html files to aid searching for things that are not in headings or routine names.
Of course, PDF files don't need this so much as the PDF viewer has nice searching tools already. We could put all the docs into a single HTML files but that will be slower on most browsers.
16. Re: Euphoria 4.0 docs
- Posted by DanM Aug 10, 2010
- 1333 views
I am glad to have the pdf in existance, i tend to use it more than the .txt of the extracted documentation, just because it's sooooo easier to search. And i hurt myself typing that because i hate pdfs.
Dan, do you have an example of what you want the help file to look like?
useless
Well, actually I'm talking about the HTML documentation, not a pdf, haven't thought about that. But for HTML doc, just an additional page, with link to it from current main page, perhaps, like this (where each entry would be a link to its section), just the chapter headings:
TOC
1 Euphoria Programming Language v4.0
2 Euphoria License
3 Quick Start
4 Language Reference
5 Syntax Reference
6 Mini-Guides
7 Included Tools
8 General Routine Reference
9 Sequence Centric Routines
10 String Centric Routines
11 Data Structures
12 Networking Routines
13 Low Level Routines
14 Graphics
15 Euphoria Routines
16 Windows Routines
17 Release Notes
Point would be that once a person knew from looking at the REGULAR main page of the docs enough times to know what kinds of info was where, then being able to select to see a specific category of interest on an ABBREVIATED, *alternative* page could be helpful.
Maybe I just get distracted too easily, but that main page is just too "busy" for me.
Dan
.jpg){kind=link}