EuDoc & Creole formatting markup

eudoc using Creole markup and euphoria can be used to document any project. much like doxygen or javadoc to create html from markup included in the source of the program and support files simplifying maintenance. euphoria users may be familiar with makedoc used in win32lib and others. eudoc is relatively new and not integrated with graphviz for ex. you can add a call to source/dis to get a dependancy graph. lexers and parsers for anything but text and euphoria files have not yet been implemented.

eudoc and creolehtml can be translated (compiled to executable) and used without a native euphoria installation.

eudoc is used to create the html manual documentation on openeuphoria and the same html can be used to ouput other formats such as pdf or chm. look in the eu4/docs directory and in eu4/include/std/*.e*
notice the markup at the top of the files and before public export or global functions and procedures.

info gleaned from posting on the dev list euforum or IRC

irc://irc.freenode.net/#euphoria
irc://irc.freenode.net/#creole
get an IRC client and try it, you'll like it.

getting started

unless you have been supplied executable versions of eudoc,

to start you need to get the source for eudoc and Creole, there may be a tarball available if you give the right url?

note: these will eventually be included with the euphoria distribution and in svn. there is currently an alpha/beta distribution but w/o eudoc & Creole.

eudoc svn
creole svn

you will also want a working euphoria version 4 which is not yet released.

http://openeuphoria.org/wiki/
http://rapideuphoria.com/

euphoria 4 svn

get an svn client and point it to euphoria 4 svn this is more efficient if you expect to update and compile your own binaries more often because it will only download what has changed. you can revert to an earlier version or only update the include directory

or expand the the archive found here and add the precompiled binaries to ./bin euphoria 4 svn/trunk.tar.gz

to save compiling your own latest svn
jeremy's http://jeremy.cowgar.com/eubins/

SDPringle unofficial patched or unchanged versions: http://euphoria.blogdns.com/

you might want to check the dev list before compiling, sometimes a chicken/egg situation can prevent compiling untill some local changes are made for one or another reason related to new syntax in the translator or include files needing a current executable to translate the code to compile.

for commandline svn

cd or md docs or whatever you call your doc dir.
cd eudoc && svn up
cd creole && svn up

from Jeremy Cowgar about eudoc and creole svn hosted on his site <jeremy@cowgar.com> Wed, Jul 9, 2008 at 1:24 AM I do not really think they should go into the euphoria source tree. Still thinking about it and we should discuss it, but they are generic tools that can be used for Euphoria source, text files, C source, and any other language that a parser is added to. In addition, once users start using eudoc, we may want to release several revisions to eudoc and do not want to release several versions of euphoria just for eudoc's sake. Further, the creole really has nothing to do with euphoria. The creole parser that Derek has created is one of the best that exists and all by itself, it's a great tool for anyone working with Creole. I can see other users of Creole learning about Euphoria because of Derek's work.

building

build.bat

exwc ..\eudoc\eudoc.ex -v -a ..\docs\eu40.af -o ..\docs\euphoria.txt
exwc ..\creole\creolehtml.ex -t=eutmpl.html euphoria.txt
rem .\creole\creolehtml.exe -t=eutmpl.html euphoria.txt
exwc ..\creole\creolehtml.ex -t=..\docs\eutmpl.html ..\docs\euphoria.txt
rem Some time passes, then the html will appear.

:* optional: assuming graphviz and eu4 source is available, just an example
echo creating dependancy graph
exwc %EUDIR%\source\dis ..\..\bin\analyze.ex --html -s -g -d appdis
echo start appdis\index.html to see the graphs

to render euphoria4 docs takes about 10+ minutes on a 1ghz cpu
simpler 40+ file projects in under a minute so the time varies.

if you translate creolehtml it goes a little faster, use the -con option MakeExe.bat to translate & compile build.bat to build edit or add options to use translated creolehtml not sure why there was no build.sh in recent svn, it was there once.

MakeExe.bat

this was originally generated by eTranslate! from the archives.

changes to reflect your local system will be required as well as changes if another compiler than watcom is used.
then recompiling is a simple double click away.

untested and slightly rewritten to be more flexible. existence of files should be tested for in a perfect world

@echo off
set PROG=creolehtml
set EUEXT=ex
set TROPS=-wat -con
:* path to upx compresser just prog name if is on path
set UPXEXE=upx
:* could use euinc.conf here?
set EU=C:\c\EU
set EUDIR=%EU%\Euwat400
set EUINC=%EUDIR%\include;%EU%\win32lib

set COMSPEC=C:\COMMAND.COM
:* set COMSPEC=C:\CMD.EXE ??

:* make sure a path to current euphoria exists
PATH=C:\WINDOWS;C:;%EUDIR%\BIN

echo path set for Watcom Compiler 
rem Win32 BAT file:
SET WATCOM=C:\c\WATCOM

PATH=%WATCOM%\BINNT;%WATCOM%\BINW;%PATH%
SET EDPATH=%WATCOM%\EDDAT
SET INCLUDE=%WATCOM%\H;%WATCOM%\H\NT
PATH=%PATH%;C:\UTIL

echo translating %PROG%
ecw %TROPS% %PROG%.%EUEXT%
echo Compiling ...
:* created by the translator
call emake.bat
:* optionally compress the executable
%UPXEXE% -9 %PROG%.exe
@echo .
@echo .
@echo Finished - please close Dos Box
exit

proj.af is a text file containing one per line paths to the files to include in order.
# can be used to comment a line in that file

TODO: need more on eudoc and creolehtml options if any, how to use proj.af and to render just one markup up file.

eudoc markup

page markup

the language/format/extension of the target file determines how eudoc looks for its markup. in euphoria it will look behind comment lines for its startup trigger (--), in text files just use the markup. in c language files it may/will be inside multiline comments /* */.

changing a few tags in the first file can determine the split as it is in eu4 double == headers go into separate output file/section. you can decide if you want one large file or bunch of separate ones.

from welcome.txt in the eu4 docs
Note: double at sign and double dollar sign are not escaping properly so drop the extra tilde's

  ~@@(title Euphoria v4.0)@
 %%maxnumlevel = 4
 %%splitname = eu_400
 %%splitlevel = 2
 %%toclevel = 3
 
 <<TOC level=3>>
 
 = Euphoria Programming Language v4.0

TOC level 3 would make === a heading in the TOC
and 4, ==== would be subheading in the TOC

• (Table Of Contents)

macros for font color & special formatting

from eu4 docs Release Notes you can change color and font
and setup macros to change the color/font for special double dollar sign parentheses sections as in the Release Notes section of the current eu4 docs describing bug fixes. Note: the color macro used in both the bugfix and doneby macro.

~@@(color <<font color="$(1)" text=`$(+)`>>)@
~@@(bugfix ****)@
~@@(doneby \\////)@

 ~* ~$~$~(bugfix) 1855414. ##open()##'s max path length is now determined by the underlying 
  operating system and not a generic default.  ~$~$~(doneby Jeremy Cowgar) 

• 1855414. open()'s max path length is now determined by the underlying operating system and not a generic default.

output of html seems to be the default but you can optionally output txt?

file and function/constant signature markup

There are two types of comments:

 --****
  -- This is a file comment, notice 4 *...
  -- This type of comment does NOT look for code to attach to it.

  --**
  -- This is a code comment. Notice the 2 *...
  -- It DOES look for code to attach, and that code it looks for
  -- is some type of valid identifier, for instance:

 -- Note: this line will be skipped because of the blank above

  export integer fh
  global procedure abc()
  enum ABC, DEF
  etc...

  --**
  -- Uses file.e

  include file.e

  will cause problems?
  
  --**
  -- Uses file.e
  --
  include file.e

  will not cause problems. no blank spaces
  notice: a blank space before ** may be significant when inside program comments?\\
  meaning don't have any space after the comment**
  as opposed to text after comments which must have space in current version.
  
  blanks before the comment {{{--}}} or no blanks after comment
  can in some cases eat chars or produce unwanted indentation.
  avoid a blank lines except just before the target 
  this for ex: will work ok with a blank line before the include
  despite what it seems to say above...
  
  --**
  -- Uses file.e

  include file.e
  

thought it was possible to have sections inside a ==== category markup. This however doesn't work. The deepest heading that allows lower level nodes is ===. Is this expected? ==== is of no practical use; ie adding it or not doesn't alter the output It goes all the way to 6 levels deep. 6 Levels deep, however, are not shown on the Table of Contents. It works just like a book. Headings too deep are not shown on the TOC otherwise the TOC would be so cluttered with such minor heading subjects as to not be useful. have not done any work on multiline code items yet. was hoping for this type of support:

export constant
   --**
   -- Greeting to give to use
   GREETING_KEY="greeting",

   --**
   -- Name of person to greet
   NAME_KEY = "name"

leading spaces are not allowed before headings with most other elements leading space is insignificant. and it's possible that leading space before headers will change to conform to a new Creole specification at some point. best not to depend on leading white space being significant.

a blank line will end a paragraph or bullet list

how to control file splitting and table of contents

-- <<LEVELTOC depth=2>>

will create a table of contents section at the top of the page

example of external file emphasized leading semicolon & colon

@[euinc.conf]
; ##-C config_file##:
: Specifies the path for a file called euinc.conf

-C config_file:

Specifies the path for a file called euinc.conf

 ; Word 
          :Definition 

links to headers in other parts of the docs. good for "see also" sections [[:header text]].

external links can be tagged with a small image in the css linked in any of the template.html, as used in euwiki

a.external {   background: url(images/external.png) right center no-repeat;
    padding-right: 12px;
 }

minimal tags so eudoc at least lists all the functions

for the example in a euphoria program file.

-- **** quad star filename/section header
-- comment lines

-- ** double star
-- comment lines
before each function, procedure, constant etc

eudoc will format any other comments up to the function signature Which it precedes with include filename\n.
please, make the parameter names descriptive and add consistent additional headers explaining parameters and example usage.
of course, when editing or patching official euphoria include files, follow the existing examples for function signature headers.

running eudoc then creolehtml will output as many html files as section headers you have for all the files named in the *.af specified to eudoc. it will link all the sections in a page TOC
the first or 2nd html will be an overall TOC table of contents.
all headers will be numbered and subnumbered and appear as links in the index.html created with simple links to all sections or linked words or external pages in the document.
this will not be a good starting point as might be expected by the name index.html, so you may want to rename one or 2 pages to suit.
Note: you should not have any unknown links in index.html so if you do, be sure to find out where the markup has gone wrong.

it may make sense to have no syntax errors in the programming file before running through eudoc. not sure it will always matter, but some language lexers and parsers may be more sensitive to errors.

exwc -TEST somefile.e will be a good check for euphoria code.

Creole markup

Text Formatting Rules

lifted from an early euwiki Creole help page,

You can freely intermix Creole markup to format page output.

Paragraphs

are created by simply typing the text. To separate paragraphs, just leave an empty line between them. Line ends will NOT be preserved inside paragraphs. You can also use "\\" to force a line break most everywhere.

Emphasis

can be marked //like this// or **like this**, to produce italic text or bold text.

Link

to a [[wikipage]] will render as wikipage. You can also use [[wikipage|different text]] that will show different text. Web page addresses, like [[http://wikicreole.org|WikiCreole]] can be also used and will display as WikiCreole.

Normal Link: http://wikicreole.org/ - now same link, but escaped: http://wikicreole.org/

Images

are included with {{http://www.wikicreole.org/templates/creole/images/viki.png|WikiCreole Logo}}, the text is displayed when the image cannot be shown. You can put images inside links:
[[http://wikicreole.org|{{http://www.wikicreole.org/templates/creole/images/viki.png|WikiCreole Logo}}]].

escape next char ~~

** no bold **

~ tilde, will remove the formatting power of the next char. for ex: so you don't inadvertently create a list with leading *.

No markup

is in effect if you type text {{{like this~}}}, or ???when you need several lines??? like this:

{{{
line 1
line 2
line 3
~}}}

Headings

are created like this:

== Section heading
=== Subsection heading
==== Subsubsection heading

trailing ='s not required in eudoc but may be in euforum or euwiki, not sure

Bullet lists

are created like this:

* first item
* second item
** first subitem of second item
* third item

• first item
• second item
  • first subitem of second item
• third item

!could be nice to select the type of bullet

Numbered lists

are made like this:

# first item
# second item
## first subitem of second item
# third item

1. item 1
2. item 2
   1. item 2.1
      1. item 2.1.1
   2. item 2.2
3. italic item 3
   1. item 3.1
      1. item 3.1.1
   2. item 3.2

FIXME: sub items are numbered wrong? maybe it's the html?
notice: leading space is not significant.

Tables

can be made easily:

| first row first column | first row second column |
| second row first column | second row second column |

Horizontal line

like this one

----

subscript super

Examples of _subscript ^super deleted inserted script.

Examples of ,,subscript,, ^^super^^ --deleted-- ++inserted++ script.

comment

!! This is a comment because it begins with two '!'

it will not be displayed or included in output in eudoc.
it may be rendered as an html comment in euwiki and will be retained in the source page/post in euwiki and euforum.

a triple 'this could be used to embed script or comment. {feature request}

Force Linebreak

To force a line break: Force\\Linebreak -> Force
Linebreak

adding blank lines works too. blank lines required to end bullet lists

Fixed width font

Fixed width font is ##text## Fixed width font

eucode tag

Example of the <eucode>...</eucode> tags
notice these have to be on a separate lines.

eudoc colorizes and depending on the css used will offset the code/text but does not format or indent the code and can only colorize euphoria as yet.

<eucode>

global function find_all(object x, sequence source, integer from)
    sequence ret 
	 
    ret = {} 
    while from > 0 with entry do 
        ret &= from 
        from += 1 
    entry 
        from = find_from(x, source, from) 
    end while 

    return ret 
end function

</eucode>

Creole links and cheat sheet

the basic markup is Creole, look it up here. WikiCreole

error's & trouble

template files

are html files, see samples in eudoc/creole/ which can include a few known plugin macros enclosed by braces to include other template files or information from creolehtml

missing template files may be caught as an error but errors in them might only be noticed in the generated output html.

template macros and contents for html generation

creolehtml will populate a field called {date} {time} ?? it is a Kanarie function Formatted as {date} = "YYYY-MM-DD hh:mm:ss GMT+n" (in 24-hour notation) Eg. "2008-07-17 13:23:10 GMT+10"

(jeremy) thinking aloud, if some how the Creole file could pass a variable to the kanarie system? For instance: %%{svn_version}=928 In the Creole source would then cause creolehtml to create a var named svn_version and it's value 928. Thus, in the footer, we could have something like: Last Updated: 2008-07-17 13:00:00 UTC from svn revision 928 The build.bat/build.sh could automatically create that revision file easy enough. Jeremy

• the date time was added, not the svn number yet. typical use in a template file called footer.html included in the main template like this {$footer.html} would be Published:{publishedon} svn 3000

{publishedon} svn 3000 (dosen't work outside of the templates)

other predefined macros can be seen in use in eu4's nav.html {thistext} {previous} {next}

some comments are in the eu4 docs maybe should add some markup to capture them as well for plugin writers?

eudoc or a plugin could be able to do automated example checking in the future? unit tests, test runner? integrated testing and documentation not yet possible, although you could add selective markup to test files to show usage. if the test functions were explained and using descriptive names and strings.

preprocessor_if links and headers

these are created by creolehtml when there is ambiguous markup

in some cases a link is inadvertently created to a non existing external file or url and will appear as a bad link in the output. see also error reporting

see also [[:outstanding bugs]],

note: section links or regular links don't work in headers, they could but it would be bad html if <Hn> was utilized to render.

are?

1. converted to 6
2. just absorbed and ignored
3. none of the above

trouble shooting

very important, when you start a section say above a function, don't add blank uncommented lines, it throws creolehtml off and possibly will crash with no obvious clue why. or you may just be missing some comments in the output.

use the tilde ~ or triple braces {{{ ~ }}} to escape any punctuation in your actual text that could be confused with valid Creole markup.

this euphoria comment will be underlined w/o ~

a table with the comparison of eudoc, euforum and euwiki use of Creole might be instructive. some of the css files have slight differences that can explain something working or not working for you in the output html. euforum and euwiki can possibly still use an earlier version of Creole which can explain differences.

it may be possible to create a page or a post on euwiki or euforum and use the preview mode to look at the output generated, then not save or publish. maybe cutting down an example section will make whatever problem in the markup more obvious.

the code for euwiki and euforum are available on jeremy's svn in euwiki and forum directories and work offline as well. (assuming you have similar setup and/or dependancies covered)

look for similar use examples in these docs, the eu4 docs and most of all try it in various ways in your own publications of pages.

take a few minutes to verify your html and css files before your users get their hands on them. templates too. w3.org or whatever local verifiers you may have

w3.org css validator http://jigsaw.w3.org/css-validator/check?uri=referer

w3.org html validator http://validator.w3.org/check?uri=referer

error reporting

a word about error checking etc, from just a guess, creolehtml is probably complicated enough, was whipped up in literally a few days then perfected in just a few weeks and used in the euwiki, eudoc and euforum. I don't know what plans the developers have for additional error reporting or parser error recovery but it is just a fact of life now you have to expect some problems if you experiment with novel use of the markup. get the minimal amount working at first and add a few things then try to make some docs and see if everything is working before adding more. good example usage are all over the eu4/include files.

adding -v option to eudoc will display the list of files processed from the prog.af file.
Note: if you have a file with an extension there is no parser for, collection of files will stop. this is probably a bug that can be confusing if not using the -v option. creolehtml also has a -v=:n option useful when dealing with problem markup. you can also define macros on the commandline, -M=: show message and a few other options which this page does not yet cover.

there is the Creole and euwiki buglist maintained on rywilly's fluidAE wiki, EuWikiBugList

a bug report with sample offending code and explanation of expected usage is appreciated. you must have a user account and be enabled to edit pages to add a bug. alternatly feel free to mention any problems on any euphoria forum or sourceforge rapideuphoria bug tracker

hopefully someone will fix any errors or omissions in due time.
some extra tilde added because of euwiki/eudoc incomplete escaping.
not escaping some markup on this page will generate a crash in creolehtml
 or euwiki. it is a problem in the page, not the program!