Historical Documenting40, Revision 1

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 user may be familiar with makedoc used in win32lib and others. eudoc is relatively new and not integrated with graphviz for ex. and 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.

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 is no distribution yet there may be a tarball available if you give the right url?

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/

[[https://rapideuphoria.svn.sourceforge.net/svnroot/rapideuphoria/trunk

euphoria 4 svn]]

http://jeremy.cowgar.com/eubins/ to save compiling your own

for commandline svn
cd or md docs or whatever you call your doc dir.
cd eudoc && svn up
cd creole && svn up
possibly you are using eudoc in more than one project and the default way the build works for eu4 will need some tweaking.

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

command line needs -A:YES for the macros to be used.
-t=eutmpl.html parameter to creolehtml.ex
does eudoc.css exist
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.
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 origionally 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 flexable. and, existance 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 UPX=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
%UPX% -9 %PROG%.exe
@echo .
@echo .
@echo Finished - please close Dos Box
exit

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

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

page markup

<<LEVELTOC depth=3>>

eudoc 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 will be inside multiline comments /* */.

changing a few tags in the first file can determine the split as it is in eu4 double == headers separate file?

so you can decide if you want one large file or bunch of separate ones.

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

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:

  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.
  sometimes just restarting build.bat will finish w/o errors, so pays to try that first...
Quoting Chris Covier & jeremy about usage and errors that may be changed or fixed by the time you read this.

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"

all headers will be numbered and subnumbered and appear as links in the html accessible from the index.html created or from the toc first file created in the sequence of html files.

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 specificationat 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 spliting 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, which holds a set of
euinc.conf
-C config_file:
Specifies the path for a file called euinc.conf, which holds a set of

leading ; or : the first char on a line does

 ; Word 
          :Definition 

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

minimal tags so eudoc at least lists all the functions

** quad star filename header & comments,

** double star comment before each function
eudoc will format any other comments up to the function signature Which it precedes with include filename\n.

make the parameter names descriptive and add additional headers explaining parameters and example usage.

Creole markup

Text Formatting Rules

lifted from an early euwiki creole help page,

You can 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 be preserved inside paragraphs. You can 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 **

* good for removing the formatting power of a char for ex: so you don't inadvertently create a list.

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

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 |
first row first column first row second column
second row first column second row second column

Horizontal line

like this one


can be used to separate parts of text, you just need to type:
----

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> tag
notice these have to be on a spearate line.

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

creole links and cheat sheet

wikicreoleCheatSheet the basic markup is creole, look it up here. WikiCreole WikiCreole Logo

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: 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.

some notes 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 some 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.

unresolved 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]

trouble shooting

very important, when you start a section above a function say, don't add blank uncommented lines, it throws creolehtml off and possibly will crash with no obvious clue why.

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.

see also [:outstanding bugs], I think there is still the creole and euwiki buglist maintained on rywilly's fluidAE wiki, home of [[http://fluidae.com/euwiki.cgi|euwiki].

hopefully someone will fix any errors or omissions in due time.

Search



Quick Links

User menu

Not signed in.

Misc Menu