Creole
Ticket #840:
save_map data for easier access to documentation
-
Reported by
SDPringle
Jan 27, 2013
Looking into html_gen.e, I see it would be trivial to save what is in search.js into a file in a format that could be loaded with load_map. This would allow any editor written in EUPHORIA, or any program that can call C functions, to provide context sensitive help on builtins and constants, and library routines.
Details
1. Comment by jimcbrown
Jan 27, 2013
Yes! That would be a very useful feature to have.
As a side note, is html_gen.e part of creole? I seem to remember otherwise...
2. Comment by SDPringle
Jan 27, 2013
Yes, it is part of creole. This is trivial to do. It is creole that creates the js/search.js pulling from a map (the std/map.e kind). I'll save it in search.dat.
3. Comment by ne1uno
Jan 27, 2013
I have done this with all the bookmark data with a forked creole, to create the CHM index files. it's about 50meg
maybe two new options,
--save-index
--save-full-index
or something similar
4. Comment by jimcbrown
Jan 27, 2013
Where's the forked creole?
Maybe we can make chm official.
5. Comment by DerekParnell
Jan 27, 2013
NO! html_gen.e is not a part of creole. It's complicated ...
Creole is creole.e. It parses creole mark up text and uses call-backs to its host application, which is expected to do any conversions required.
The html_gen.e file that comes with the creole package is an example only of how the example application (called creole.ex) could be written to convert creole mark up to html.
The Eu web site has its own application to do markup to html conversion that uses its own html_gen.e file.
The documenation generation is done with another application an also has its own version of html_gen.e to create Docmentation html files.
So to repeat, html_gen.e is not a part of creole.
6. Comment by jimcbrown
Jan 27, 2013
Thanks for the clarification, Derek.
So, um, wow. Three different and totally unrelated html_gen.e programs...
7. Comment by SDPringle
Jan 27, 2013
Now in the "example", html_gen.e that is in the creole checkout directory, nonetheless I had added save_map call in there. I compiled creole, put it at the beginning of my PATH environment variable and then went to my EUPHORIA 4.0 checkout source subdirectory. I ran 'make htmldoc' and then browsed to the html sub directory of the build directory. I found 'search.dat'. So, creole does use the file. It is used in creating the html documentation we distribute to on each release of EUPHORIA.
Perhaps Derek is mistaken here.
The first lines of the file looks like this:
"\"allsorts.ex\"" = {{"allsorts","_323_allsortsex","\"Bundled Demos\""}}
"\"EXT_SIZE\"" = {{"std_filesys","_1485_ext_size","\"File System\""}}
"\"Disclaimer:\"" = {{"e2c","_629_disclaimer","\"Euphoria To C Translator\""}}
"\"declare an enumerated value\"" = {{"syntax","_228_declareanenumeratedvalue","\"Formal Syntax\""}}
"\"has_match\"" = {{"std_regex","_3281_has_match","\"Regular Expressions\""}}
"\"In\-lining of Routine Calls\"" = {{"perform","_722_inliningofroutinecalls","\"Performance Tips\""}}
"\"Lock Type Constants\"" = {{"std_eds","_4121_locktypeconstants","\"Euphoria Database (EDS)\""}}
In particular, has_match has bookmark "_3281_has_match". When I browse to the build/html/allsorts.ex and do a search. I see it is at std_regex.html#_3281_has_match.
8. Comment by DerekParnell
Jan 28, 2013
No, I'm not mistaken. I wrote creole so trust me, I actually know something about it.
Please note that when I refer to 'creole' I mean specifically the file called "creole.e". In the project for creole, in the repository, there is a file called "creole.ex". That is an EXAMPLE program of how one might use creole to do something useful. It is "creole.ex" that includes "html_gen.e" as creole itself (i.e. "creole.e") does not know anything about HTML, JS, or any form of output representation of the mark up text.
One could write any program that includes "creole.e" (eg. "htlmdoc.ex") that implements the call backs used by creole.e and those callbacks do not have to exist in "html_gen.e" - they can be in any file. Creole doesn't care one iota where it's host application implements the call back routines.
9. Comment by jimcbrown
Jan 28, 2013
Yes, I remember it now.
http://scm.openeuphoria.org/hg/euweb/rev/b15ad198870f
http://sourceforge.net/mailarchive/forum.php?thread_name=20120405175750.GA21374%40jbrown.linuxbuddhist.net&forum_name=rapideuphoria-develop
There's only one version of html_gen.e after all, but euweb and the docs piggy-back on this "example" that, although not formally part of the Creole library, ships with it and is not available separately. Even though originally intended as an example only (in the same way that w32lib and llamagtk ship with demo programs that serve as examples to demonstrate the functionality of their respective libraries, but which are not part of the libraries that they ship with), that plugin has become an essential and necessary part of the code that powers the website, and it will need to be maintained and upgraded accordingly.
Although this may go against the intention of the original author, since html_gen.e ships with Creole and we don't have a separate product space for it, tickets involving html_gen.e should probably go under the Creole product.
Considering that Jeremy, myself, Matt, and Shawn (in that order) have gotten confused about the nature of html_gen.e, someone should probably update the Creole documentation regarding the nature of the plugins along with a thorough explaination on why they should not be considered part of the Creole library. (That probably won't stop confusion in the future - who reads documentation these days? :) - but at least then it'll be a simple "READ THE FAQ" answer.)
10. Comment by mattlewis
Jan 28, 2013
I understand Derek's point. However, for those of us not inside his head 
, there is a creole repository / project, a creole.e library file and a creole.ex program. We should probably rename creole.ex to something like creole2html.ex for clarity.
We might also restructure the repository to put that and its html_gen.e file into their own directory or something to emphasize its nature. We could also move the creole.e library into its own include or library directory.
Alternatively, we could put html_gen.e and creole2html.ex in the eudoc repository and simply specify that creole is a dependency. I'm not sure I like this, as the creole2html is useful for other things. I use it (and I know Jeremy does) to maintain some project web pages written in creole.
11. Comment by mattlewis
Jan 28, 2013
Shawn's comment accidentally put onto ticket 820:
See: hg:creole/rev/12d841bc7dd2
changeset: 109:12d841bc7dd2 tag: tip user: Shawn Pringle <shawn.pringle@gmail.com> date: Mon Jan 28 00:40:31 2013 -0300 files: html_gen.e description:
save a file of the map used to find URLs for routine and constant names fixes ticket 820
GitHub