Wiki Diff Documenting40, revision #3 to tip
<<TOC level=3>>
= 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.
[[http://jeremy.cowgar.com/svn/eudoc/trunk/|eudoc svn]]\\
[[http://jeremy.cowgar.com/svn/creole/trunk/|creole svn]]
you will also want a working euphoria version 4 which is not yet released.
[[http://openeuphoria.org/wiki/]]\\
[[http://rapideuphoria.com/]]
!!seems like a bug that urls can't span lines
[[https://rapideuphoria.svn.sourceforge.net/svnroot/rapideuphoria/trunk|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
[[http://rapideuphoria.svn.sourceforge.net/viewvc/rapideuphoria/trunk.tar.gz?view=tar|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.
:setup directories like so\\
eu4/docs/eudoc/creole
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
!!this will go on a seperate page win/nix bat & script
=== build.bat
:command line needs -A:YES for the macros to be used.
:-t=eutmpl.html parameter to creolehtml.ex
{{{
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
!!<eucode language=bat>
{{{
@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
}}}
!!can eucode be uppercase? MixedCase?
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
!!TOC just shows the overall toc of this file
<<LEVELTOC depth=3>>
=== 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 **$$(color #009999 bug fixed:)**)@
~@@(doneby \\//$$(color #999900 Implemented by: $(0))//)@
~* ~$~$~(bugfix) 1855414. ##open()##'s max path length is now determined by the underlying
operating system and not a generic default. ~$~$~(doneby Jeremy Cowgar)
}}}
@@(color <<font color="$(1)" text=`$(+)`>>)@
@@(bugfix **$$(color #009999 bug fixed:)**)@
@@(doneby \\//$$(color #999900 Implemented by: $(0))//)@
* $$(bugfix) 1855414. ##open()##'s max path length is now determined by the underlying
operating system and not a generic default. $$(doneby Jeremy Cowgar)
!!Note: this section is not currently rending the same as eudoc
!!because euwiki is using an earlier euphoria and creole
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 should probably say commands rather than 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
}}}
!!how do I setoff a section like a no format div but with formatting?
|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"
}}}
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
;using all the depth= headers, so depth=2 would use ~=== headers?
little confusing here since ~== will cause a page split as well.
example of external file emphasized leading semicolon & colon\\
{{{
@[euinc.conf]
; ##-C config_file##:
: Specifies the path for a file called euinc.conf
}}}
@[euinc.conf]
; ##-C config_file##:
: Specifies the path for a file called euinc.conf
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]]. }}}
!!%%style=floatright / floatleft
!!%(
!!seems to be euwiki only, maybe euforum too?
!!)%
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.
!!unescaped use here crashes creolehtml
~-- {{{****}}} 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.
!!Possibly lift a function sig from one of the include files for example
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
!!could include page {CreoleHelp}
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 [[wiki page|different text]]. Web page addresses, like {{{[[http://wikicreole.org|WikiCreole]]}}} can be also used and will display as [[http://wikicreole.org|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
}}}
# [[item 1]]
# item 2
## item 2.1
### item 2.1.1
## item 2.2
# // italic item 3 //
## // item 3.1 //
### // item 3.1.1 //
## // 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 '!!!' might be used for comments or code intended for output html/text
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##>
<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>
</##eucode##>
==== Creole links and cheat sheet
!!this is working in the rendered docs, but how to adjust height & width?
!!not sure I can just copy this image for official docs either
!!should these comment be in the generated docs? maybe !!! gen comment
!! {{{<!-- include comment in generated doc is not working -->}}}
{{images/wikicreoleCheatSheet.png|wikicreoleCheatSheet}}
the basic markup is Creole, look it up here.
[[http://wikicreole.org|WikiCreole]]
{{http://www.wikicreole.org/templates/creole/images/viki.png|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:
{{{%%{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
=== 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]]
!!is this the format? I'm not getting links here
====== 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.
======= header markup of more than 6 equal sign
are?
# converted to 6
# just absorbed and ignored
# none of the above
!!would be nice to allow alpha a,b,c as well as numbered lists
=== 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 ~--
:does base.css exist is style.css used in any template files?
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
[[http://jigsaw.w3.org/css-validator/validator?profile=css21&warning=0&uri=|w3.org css validator]]
http://jigsaw.w3.org/css-validator/check?uri=referer
[[http://validator.w3.org/check?verbose=1&uri=|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,
[[http://fluidae.com/euwiki.exu?EuWikiBugList|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 [[https://sourceforge.net/tracker2/?func=browse&group_id=182827&atid=902782|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!
}}}
= 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.
[[http://jeremy.cowgar.com/svn/eudoc/trunk/|eudoc svn]]\\
[[http://jeremy.cowgar.com/svn/creole/trunk/|creole svn]]
you will also want a working euphoria version 4 which is not yet released.
[[http://openeuphoria.org/wiki/]]\\
[[http://rapideuphoria.com/]]
!!seems like a bug that urls can't span lines
[[https://rapideuphoria.svn.sourceforge.net/svnroot/rapideuphoria/trunk|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
[[http://rapideuphoria.svn.sourceforge.net/viewvc/rapideuphoria/trunk.tar.gz?view=tar|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.
:setup directories like so\\
eu4/docs/eudoc/creole
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
!!this will go on a seperate page win/nix bat & script
=== build.bat
:command line needs -A:YES for the macros to be used.
:-t=eutmpl.html parameter to creolehtml.ex
{{{
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
!!<eucode language=bat>
{{{
@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
}}}
!!can eucode be uppercase? MixedCase?
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
!!TOC just shows the overall toc of this file
<<LEVELTOC depth=3>>
=== 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 **$$(color #009999 bug fixed:)**)@
~@@(doneby \\//$$(color #999900 Implemented by: $(0))//)@
~* ~$~$~(bugfix) 1855414. ##open()##'s max path length is now determined by the underlying
operating system and not a generic default. ~$~$~(doneby Jeremy Cowgar)
}}}
@@(color <<font color="$(1)" text=`$(+)`>>)@
@@(bugfix **$$(color #009999 bug fixed:)**)@
@@(doneby \\//$$(color #999900 Implemented by: $(0))//)@
* $$(bugfix) 1855414. ##open()##'s max path length is now determined by the underlying
operating system and not a generic default. $$(doneby Jeremy Cowgar)
!!Note: this section is not currently rending the same as eudoc
!!because euwiki is using an earlier euphoria and creole
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 should probably say commands rather than 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
}}}
!!how do I setoff a section like a no format div but with formatting?
|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"
}}}
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
;using all the depth= headers, so depth=2 would use ~=== headers?
little confusing here since ~== will cause a page split as well.
example of external file emphasized leading semicolon & colon\\
{{{
@[euinc.conf]
; ##-C config_file##:
: Specifies the path for a file called euinc.conf
}}}
@[euinc.conf]
; ##-C config_file##:
: Specifies the path for a file called euinc.conf
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]]. }}}
!!%%style=floatright / floatleft
!!%(
!!seems to be euwiki only, maybe euforum too?
!!)%
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.
!!unescaped use here crashes creolehtml
~-- {{{****}}} 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.
!!Possibly lift a function sig from one of the include files for example
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
!!could include page {CreoleHelp}
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 [[wiki page|different text]]. Web page addresses, like {{{[[http://wikicreole.org|WikiCreole]]}}} can be also used and will display as [[http://wikicreole.org|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
}}}
# [[item 1]]
# item 2
## item 2.1
### item 2.1.1
## item 2.2
# // italic item 3 //
## // item 3.1 //
### // item 3.1.1 //
## // 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 '!!!' might be used for comments or code intended for output html/text
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##>
<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>
</##eucode##>
==== Creole links and cheat sheet
!!this is working in the rendered docs, but how to adjust height & width?
!!not sure I can just copy this image for official docs either
!!should these comment be in the generated docs? maybe !!! gen comment
!! {{{<!-- include comment in generated doc is not working -->}}}
{{images/wikicreoleCheatSheet.png|wikicreoleCheatSheet}}
the basic markup is Creole, look it up here.
[[http://wikicreole.org|WikiCreole]]
{{http://www.wikicreole.org/templates/creole/images/viki.png|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:
{{{%%{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]]
!!is this the format? I'm not getting links here
====== 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.
======= header markup of more than 6 equal sign
are?
# converted to 6
# just absorbed and ignored
# none of the above
!!would be nice to allow alpha a,b,c as well as numbered lists
=== 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 ~--
:does base.css exist is style.css used in any template files?
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
[[http://jigsaw.w3.org/css-validator/validator?profile=css21&warning=0&uri=|w3.org css validator]]
http://jigsaw.w3.org/css-validator/check?uri=referer
[[http://validator.w3.org/check?verbose=1&uri=|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,
[[http://fluidae.com/euwiki.exu?EuWikiBugList|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 [[https://sourceforge.net/tracker2/?func=browse&group_id=182827&atid=902782|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!
}}}
