darioteixeira / lambdoc

=========================================================================
| README for Lambdoc                                                    |
|                                                                       |
| http://lambdoc.forge.ocamlcore.org/                                   |
|                                                                       |
| Dario Teixeira <[email protected]>                           |
=========================================================================


1. Overview
===========

Lambdoc is a library providing support for semantically rich documents in web
applications, built with Ocsigen/Eliom [1] integration in mind.  It includes
parsers for four different markup languages: Lambtex, Lambxml, Lambwiki,
and Markdown.  The first is inspired by LaTeX, the second is an XML-based
markup based on HTML, the third is a lightweight markup language in the spirit
of Wiki Creole, and the last is the popular lightweight markup language.
The library also includes the possibility of outputing any Lambdoc document
as an Ocsigen (TyXML) HTML value.

Additional capabilities include the runtime customisation of available
document features (you may, for example, declare that a certain class of
users is only allowed to produce documents containing nothing more than
paragraphs of plain text), detailed error messages, and the definition of
basic macros.  Particularly of note is a powerful extension mechanism that
allows the definition of custom commands tailored to a particular application.
It also ships with 'lambcmd', a CLI application that allows the conversion
between any of the input formats into one of the supported output targets.


2. Dependencies
===============

The library depends on Blahcaml [2], Camlhighlight [3], Menhir [4], OCaml-re [5],
Sedlex [6], Sexplib [7], TyXML [8], and Xmlm [9].  The CLI application 'lambcmd'
depends also on Cmdliner [10], and the unit tests depend on Alcotest [11].


3. Building and installing
==========================

The build system relies on OASIS.  The customary sequence of './configure',
'make', and 'make install' is used to build and install the library and the
lambcmd CLI application.  Run 'make doc' to generate the API documentation.


4. License
==========

Lambdoc is distributed under the terms of the GNU GPL version 2.
See LICENSE file for full license text.


5. Notes on the provided CSS
============================

Inside the 'css' directory you will find the sample CSS adapted to the HTML5
output generated by the Lambdoc_whtml5_writer module.  It is fairly simple yet
pleasant looking, and a good starting point if you want to customise it for
your own sites.

You will note that most elements are given their own class name, prefixed
by the identifier 'doc'.  Inline bold elements, for example, are identified
by the class 'doc_bold'.  This solution was preferred over the alternative
of referrencing '.doc b' because it has much better performance.  It does
have the disadvantage of producing larger markup, however.


References
==========

 [1] https://www.ocsigen.org/
 [2] https://blahcaml.forge.ocamlcore.org/
 [3] https://camlhighlight.forge.ocamlcore.org/
 [4] https://cristal.inria.fr/~fpottier/menhir/
 [5] https://github.com/ocaml/ocaml-re
 [6] https://github.com/alainfrisch/sedlex
 [7] https://github.com/janestreet/sexplib
 [8] https://www.ocsigen.org/tyxml
 [9] https://erratique.ch/software/xmlm
[10] https://erratique.ch/software/cmdliner
[11] https://github.com/mirage/alcotest