From cb88d60e8e6d716668cf96daaffad7590b8f3f4f Mon Sep 17 00:00:00 2001 From: Leo Valais Date: Fri, 4 Jan 2019 12:33:00 +0100 Subject: [PATCH 1/2] doc: add final draft --- doc/2.0/manual/intro.wiki | 537 +++++++++++++++++++++++++++++++++++++- doc/2.0/manual/menu.wiki | 22 ++ 2 files changed, 557 insertions(+), 2 deletions(-) create mode 100644 doc/2.0/manual/menu.wiki diff --git a/doc/2.0/manual/intro.wiki b/doc/2.0/manual/intro.wiki index e669fd2a..76181f4a 100644 --- a/doc/2.0/manual/intro.wiki +++ b/doc/2.0/manual/intro.wiki @@ -1,2 +1,535 @@ -= html_of_wiki -Work in progress, please come back later! \ No newline at end of file +<> + +=html_of_wiki +<
> is a versatile, minimalist yet powerful **static website generator**. + It is designed with simplicity in mind: no special directories, almost no configuration + and everything working out of the box. No web server required, just the compilation of + your content to HTML and you're free to choose which static files server service fits you: + GitHub Pages, GitLab Pages, etc. + + It allows writing website content in a feature-rich and extensible language: the **wikicréole**. + This language, thanks to its clever design, allows to write rich content as much + expressively as with plain HTML. + + <> is part of the Ocsigen project and is used to generate its documentation---including this page! + It has no problem dealing with large websites, it can handle several versions of several projects. + + <> is also composable, it can be integrated into a CI/CD process so you can automate + the deployment of your website. Rebuild and deploy on each commit! +>> + +==@@id="install"@@Installation +Clone this repository: +{{{ +$ git clone https://github.com/ocsigen/html_of_wiki.git +}}} +then, use ##opam pin## to install it: +{{{ +$ opam pin add -y html_of_wiki html_of_wiki +}}} + +==What you will learn here +The following sections describe: + +# The wikicréole format +# How to use ##ohow##, a wikicréole compiler to HTML +# How to use +## ##dop## for generating the documentation of a whole project's version, and +## ##quickdop## for generating the documentation of a whole project's. +# The available extensions (TODO) +# A brief introduction to ##html_of_wiki##'s internals (TODO) + +=The wikicréole +==@@id="wikistd"@@The standard +The following picture summarises the wikicréole 1.0 format. + +<> + +**Notes**: +* The wikicréole supported by ##html_of_wiki## uses only one {{{=}}} sign for toplevel headings. +* There is also the tilde character {{{~}}} for not interpreting the character it prefixes. + +==@@id="wikiadd"@@Syntax additions +===Supported links syntaxes +The following table lists additional link syntaxes supported by the tool. +|=Syntax |=Description | +|{{{[[wiki("name"):page]]}}}|Link to the ##page## of the project ##name##| +|{{{[[wiki:page]]}}} |Link to the ##page## of the current project | +|{{{[[site:page]]}}} |Website root-relative link | +|{{{[[href:path]]}}} |Raw ##href## value | + +The following table lists available links abbreviations. +|=Abbreviation |=Equivalent syntax |=Description | +|{{{[[]]}}} |{{{[[href:.]]}}} |Current page | +|{{{[[#anchor]]}}}|{{{[[href:#anchor]]}}}|Current page with anchor | +|{{{[[/path]]}}} |{{{[[site:path]]}}} |Website root-relative link| +|{{{[[path]]}}} |{{{[[href:path]]}}} |Relative link | + +===Decorations +The following table lists the additional available decorations. +|=Syntax|=Description|=Example| +|{{{--}}} |//en-dash// |--| +|{{{---}}} |//em-dash// |---| +|{{{##text##}}} |Mono-spaced font|##text##| +|{{{^^super^^}}}|Superscript |text^^super^^| +|{{{,,sub,,}}} |Subscript |text,,sub,,| +|{{{__text__}}} |Underline |__text__| +|{{{/-text-/}}} |Strike-through |/-text-/| + +===Definition lists +The following code produces a definition list. +{{{ +;title1 +:definition1 +;title2 +:definition2 +}}} + +;title1 +:definition1 +;title2 +:definition2 + +===Inline HTML classes +It is possible to inline some HTML classes to the following element using the syntax ##~@~@class="title"~@~@##. + +===Extensions +The wikicréole supported by ##html_of_wiki## support **extensions**, a powerful +mechanism that allows executing arbitrary OCaml code registered to the parser. +More detail about this mechanism can be found in the last section of this document. + +Extensions syntax: {{{<>}}} + +Here are some common, widely used by Ocsigen's documentation extensions: +; {{{<>}}} +: Link to a page of the manual of a project. +; {{{<>}}} +: Inserts an HTML {{{}}} element allowing a fine control over the DOM of the page. +; {{{<>}}} +: Displays a menu like the one on the left of this text. + +=@@id="ohow"@@How to use ##ohow## (one_html_of_wiki) +**one_html_of_wiki** is a CLI tool for generating a //single// HTML document from a //single// wikicréole file. + +==Basic usage +{{{ +$ ohow file.wiki # generates file.html +$ ohow -o somename.html file.wiki # generates somename.html +$ ohow --help # shows help +$ ohow --version # shows version +$ ohow --print file.wiki # prints the HTML to stdout instead of writing a file +$ ohow --headless file.wiki # do not include HTML head nor wrapping body tag +$ ohow --local file.wiki # generate local-navigation compatible links (REMOVE THAT FOR DEPLOYMENT) +}}} + +==Advanced usage +===@@id="templates"@@Templates +one_html_of_wiki supports the use of //templates//. A template is a classic wikicréole file which contains a (unique occurrence of) {{{<>}}} somewhere. It is where the content will be inserted. + +Consider the following example for a deeper understanding on how to use templates: +{{{ +$ cat template.wiki +<> +@@class="red"@@Before. +<
> +>> +@@class="red"@@After. +$ +$ cat page.wiki +I'm a wiki page, providing some <> content! +$ +$ ohow --template template.wiki --print page.wiki +

Before. +

I'm a wiki page, providing some +useful content!

+

After.

+$ +}}} + +====wiki_in_template +If the template has to contain more than one {{{<>}}} tag or if several templates have to be used, the integration of ##wit## to your workflow has to be considered. +//wiki_in_template// (##wit##) is a simple CLI tool for inserting content inside templates without converting them into HTML: it only deals with wikicréole. + +Here's an example of how to use it to insert one page inside several templates: +{{{ +$ ls +bottom.wiki hello.wiki top.wiki +$ cat hello.wiki +=Hello world! +This is the content wiki. +$ cat top.wiki +Template above. +<> +$ cat bottom.wiki +<> +Template below. +$ +$ cat hello.wiki | wit top.wiki | wit bottom.wiki +Template above. +=Hello world! +This is the content wiki. +Template below. +$ +}}} + +And an example of how to insert several pages inside one template: +{{{ +$ ls +title.wiki text.wiki template.wiki +$ cat title.wiki +=Hello world! +$ cat text.wiki +Some text. +$ cat template.wiki +Before first. +<> +In between. +<> +After. +$ +$ wit <(wit template.wiki < title.wiki) < text.wiki +Before first. +=Hello world! +In between. +Some text. +After. +$ +}}} + +Finally, as far as ##wit## is concerned, a page is a wiki file without {{{<>}}} and a template is a wiki file with at least one occurrence of {{{<>}}}---so there's nothing wrong in saying that ##wit## can output a template. + +A few notes: +* You cannot escape the string {{{<>}}} or {{{<>}}} using the three curly braces syntax. +* You cannot write a comment with the string {{{<>}}} or {{{<>}}} inside. + +===@@id="linkexts"@@Link extensions +There are several link extensions that ship with ##ohow##. They differ from the classic link syntax because they do not explicitly state where is located the resource to link. For example, {{{<>}}} leads to the chapter ##intro## of the ##eliom## project //without explicitly giving the location of that page//. + +Here are the available extensions: +* {{{<>}}} +* {{{<>}}}, {{{<>}}} and {{{<>}}} +* {{{<>}}} +* {{{<>}}} + +and the attributes they accept: +|=Attribute |=Extensions |=Description |=Default value | +|##project## |All except ##a_img## and ##a_file## |The project of the page |Current project | +|##chapter## |##a_manual## |The manual chapter to link |None | +|##subproject##|##a_api##, ##a_api_type##, ##a_api_code##|The targeted sub-project |None | +|##text## |##a_api##, ##a_api_type##, ##a_api_code##|Text of the produced link |What's documented| +|##version## |All except ##a_img## and ##a_file## |The version of the project containing the page|{{{latest}}} | +|##fragment## |All except ##a_img## and ##a_file## |HTML fragment |None | +|##src## |##a_img##, ##a_file## |The path to the resource to link |//Required// | + +However, even if the extensions doesn't require the //writer// to explicitly give the linked resource's location, the compiler still needs to know where to find it. It is why, whenever any of these extensions is used inside a wiki document, the writer must call ##ohow## with the correct values for these options: {{{--manual}}}, {{{--api}}}, {{{--images}}}, {{{--assets}}} and {{{--root}}} (the latter defaults to the current working directory). + +The //root// directory is the directory containing all wiki content for a specific project's version. For example, a project ##proj/##, with two versions, ##1.0/## and ##2.0/##, each one containing the ##man/##, ##api/## and ##assets/## directories. ##ohow## must then be called with the following options ({{{pwd = ~/user/proj/}}}): +* {{{--root 2.0/}}} +* {{{--manual man/}}} --- The path is relative to the //root// directory (not the current directory!). You could still have used {{{--manual 2.0/man/}}} (the root prefix is automatically stripped away). +* {{{--api 2.0/api/}}} --- or equivalently, {{{--api api}}} +* {{{--assets assets}}} +* ({{{--images assets}}} --- Only if you used {{{a_img}}} and that the images are in the ##assets/## directory.) + +For inter-project links, ##ohow## **supposes that every projects are inside the same directory**. For example, {{{<>}}} will produce the following link: ##<>/../../<>/<>/<>##. +The first ##../## rewinds from the root directory into the project directory (containing all versions). +The second ##../## rewinds inside the directory containing all the projects. +It could, in practice, look like ##../../../../eliom/latest/man/intro. + +html_of_wiki imposes these constraints for links because these are the constraints GitHub Pages imposes. To conclude, setting up these extensions is not as complicated as it sounds (it's roughly passing some paths to ##ohow## through command line arguments) and the benefits are huge: this way you abstract away any hierarchy between wiki pages and projects and let the compiler work out the links by itself. Thus, any structural change of your projects **will not** force you to rewrite your documentation! + +===@@id="doctree"@@The {{{<>}}} extension +{{{<>}}} is an extension without parameters that inserts a menu. That menu is built by concatenating the content of all the files named ##menu.wiki## inside the //root// directory. The order is: +# the ##menu.wiki## of the manual first, if any +# the ##menu.wiki## files of the API, if any, alphabetically sorted by sub-project's name, if any + +For example, for a project with a manual and two API sub-projects, the extension will look for the following files, in that order: +# ##manual/menu.wiki## +# ##api/menu.wiki## +# ##api/sub-project1/menu.wiki## +# ##api/sub-project2/menu.wiki## + +The menu on the left of this text is generated using that extension. +Here is an example of what one can put inside a ##menu.wiki## file: +{{{ +=##html_of_wiki## +==[[#title|Introduction]] +=The wikicréole +==[[#wikistd|Standard]] +==[[#wikiadd|Additions]] +=[[#ohow|##ohow##]] +}}} +Again, that extension requires some extra parameters---{{{--root}}}, {{{--manual}}} and {{{--api}}}---which are described above. The generated element is a {{{