This is the manual of bhl version 1.8rc1.
bhl is an Emacs mode that enables you to convert a plain text file into an HTML, SGML, LaTeX, Texinfo, Wiki and TXT file. Since you can run bhl offline, it's also a standalone format: writing a bhl file makes it ready for generic conversions.
“bhl” is an acronym for: Brute (i.e. “plain”) to Html and LaTeX.
I have been asked if there was an easy way to pronounce
“bhl”. Yes, there is. Bhl- is the indo-european
root for “blow” (and derivative but less poetic verbs like
“blather”). So, just say “blow”.
bhl is a text formatting and publishing tool. It is an Emacs mode that provides two kinds of tools: tools for editing a plain text file as an implicitly structured document, and tools for converting this document into other formats: HTML, SGML, LaTeX, Texinfo and TXT.
In order to be readable by bhl, a plain text file must fit some syntactic conventions. This conventions are neither completely universal nor specially odd. They are chosen among the most useful and the most convenient text formatting conventions. The purpose of this mode is to use the most invisible and convenient syntax. “Invisible syntax” means that the source file must be as readable as possible – like any plain text file must be. “Convenient syntax” means that it must fit the users' habits.
For example, *word* appears in bold; _word_ appears in
emphasis; lists and URLs follow StructuredText or Wiki
conventions; the numbering of sections respects logic and intuition.
(See The syntax.)
In short: there is nothing you have to learn to write your documents with the bhl mode (just try, it's true).
bhl is not WYSIWYG since you are only editing text.
bhl is not WYSIWYM (like LyX), since what you
mean is editing text. So, what is bhl? It is
WYSIWYS(IWYS): What You See Is What You See (Is What You See).
Editing text is editing text.
You have just downloaded bhl.tar.gz on http://www.nongnu.org/bhl. Untar the archive like this:
~$ tar zxvf bhl.tar.gz
Go to the bhl-*/ directory and set up the Makefile. Once this is done, just compile and install like this:
~$ make
~$ make install
If you want to install bhl in your /usr/local/ or
/usr/share/ paths, you need to have superuser
(i.e. root) permissions. But don't worry: at the end of the
install procedure, a message tells you if something has gone wrong.
If you want to generate and install the bhl.info file:
~$ make info
~$ make install-info
If you want the printed manual (PDF):
~$ make pdf
If you want the HTML manual:
~$ make html
If you want to clean up the directory:
~$ make clean
You can add these lines to your ~/.emacs.el:
(autoload 'bhl-mode "bhl" "BHL Mode" t)
(add-to-list 'auto-mode-alist '("\\.bhl$" . bhl-mode))
The last line enables you to associate a new extension
(i.e. .bhl) with the bhl editing mode, so that bhl will
automatically be loaded when you open a .bhl ending file.
Ordinarily, a plain text file has no visible or invisible syntax. To be bhl-readable, a file has to respect some conventions.
The title is mandatory. bhl tries to read it in the very first lines of the buffer. The title is on a line that does not include any newline or tab character.
The subtitle is not mandatory. It is currently included in the HTML, TXT and Texinfo output. You can include it as a specification, like this:
#!subtitle!My subtile subtitle
For details on how to format and insert specifications, See Specifications.
The paragraphs always begin at the beginning of the line. Don't indent paragraphs: restrict indentation to lists.
bhl handles three levels of section: sections, subsections and subsubsections.
bhl handles five different sectioning styles: num,
alpha, aster, equal-sign and user-defined.
The default style is set to numerical.
Here is a table with examples of each sectioning style:
numalphaasterequal-signYou can choose the default style of sectioning by modifying bhl-sectioning-default-style. This is the default sectioning style for any newly created bhl file.
When you find an already existant bhl file, bhl
tries to guess its sectioning style, if you've set
bhl-autoguess-style-flag to t – which is its default
value. At any time, you can ask bhl to guess the style with
bhl-guess-style, which is bound to <C-c M-s> (and also
available from the menu, as usual).
For example, suppose you are using the alphabetical style in
foo.bhl and your bhl-sectioning-default-style is set to
num, then bhl will automatically turn the current
style to alpha. If bhl is not able to recognize any
style, it sets the sectioning style to the value of
bhl-sectioning-default-style.
Don't mix sectioning styles! If bhl finds a numerical section, it will consider that all the (sub)sections are numerical, which is actually rather stupid, but I've no time for this at the moment.
You can switch from one style to another style from the menu or with bhl-sectioning-switch-style. This command reads a style from the minibuffer and converts the (sub)sections' prefix into the chosen style.
If you choose to use your own style, you have to manually customize
bhl-my-sectioning-regexp-list. See Global options. This
variable includes a list of the three regular expressions that match
respectively the sections, subsections and subsubsections. Please
note that bhl-udpate-toc won't work anymore if you set
bhl-sectioning-default-style to my.
You can update the sections' prefix (numbers or letters) with <C-c M-t>, which is the default key binding for bhl-update-toc.
This section describes the use of font beautifiers, environments and horizontal rules.
Font beautifiers allow you to emphasize, underline, boldify and truetypify some words.
In the SGML and Texinfo outputs, underline means put in italic, just like emphasis. In the HTML and LaTeX output, underline means underline truly.
If you want to put your text in bold-italic, use _*this order*_
rather than *_this order_*. Note that bold-italic is not
available in the Texinfo output.
If you want to insert an underscore or an asterisk that has no
syntactic meaning, put an escape character before: \* and
\_. The same is possible with the comment character
#. See Comments.
You can choose a font beautifier for a specific region with the bhl-change-font- commands. See Changing font.
Here are the tags to be used in your bhl file if you want to change the fonts:
The character for introducing new comments is #.
You can insert comments wherever you want, but comments always end at the end of the current line. There is no “ending-comment” character.
If you want to insert a # which should not introduce a new
comment, use the escape sequence \#.
You can comment the current region with bhl-comment-region <C-c ;> and uncommment it by adding a symbolic prefix to bhl-comment-region <C-u C-c ;>.
You can make comments invisible with bhl-hide-comment and make them visible again with C-u bhl-hide-comment.
bhl handles three environments: quote,
verbatim and minipage. The first one quotes some part
of text. The second one may be useful for inserting code into a
documentation. The third one creates a minipage inside the main page,
with or without borders.
To quote some part, just add one single tab in the beginning of each line. Here is an example:
Put some words here.
Put some words here.
Put some words here.
Put some words here.
Here is the syntax of the verbatim environment:
--
Put some words here.
--
Attention: two dashes are the default delimiters for the
verbatim environment, while four dashes are markers for
horizontal rules.
Remember that the highlighting of dashes indicates the syntaxic role they play when bhl-special-face differs from bhl-hr-face (which is the default case). See Horizontal rules.
The bhl-verbatim-ignore variable contains a list of syntactic elements that have no meaning inside a verbatim environment. This means that those syntactic elements won't be converted, even if they are fontified. See Global options.
Here an example of how to insert a minipage:
%%%[12cm]
This minipage (12cm) will be centered without border.
%%%
<%%[10cm]
This minipage (10cm) will be put on the left without border.
%%%
>-%
This minipage will be put on the right with borders.
%%%
The basic indicator for the beginning and the end of a minipage
environment is %%% at the beginning of a line. This indicates
a centered minipage, without border and of the same width as the main
page.
By replacing the first % with a < or a >, you
put the minipage respectively on the left or on the right. For
example, <%%%% indicates a left aligned minipage which has the
same width as the main page.
By replacing the second % with a dash (-), you put solid
borders on the minipage. For example, <-%%%%% indicates the
beginning of a minipage that has the same width as the main page, put
on the left with solid borders.
The length can be put into square brackets like this: %%%[8cm].
It is optional. Avoid using relative lengths such as “40%”: the
% character is syntax-sensible in the LaTeX environment. Use
only absolute lengths and common units.
Minipages are properly converted only for the HTML, LaTeX and Texinfo
outputs. For the Texinfo output, you can choose what a centered
minipage looks like with bhl-texi-centered-minipage-tag. For
the SGML output, you can choose what a minipage looks like with
bhl-sgml-minipage-tag. bhl2txt does not convert
minipages, it simply strips the %%% at the beginning of the
line.
You can insert a minipage with bhl-insert-minipage. See Inserting.
A horizontal rule is represented by at less four dashes (---- -
Small), equal signs (==== - Large) or slashes (//// -
X-Large) at the beginning of a line.
The first character can be replaced by an indicator of alignment.
Attention: horizontal rules are not converted in the SGML and Texinfo formats.
----[12cm]
<---[12cm]
>---[12cm]
The first line will be centered. The second line will be put on the
left. The third line will be put on the right. The width of these
lines is 12cm. The length is optional: you can simply insert
----, ==== or ////.
You can insert a horizontal rule with bhl-insert-hr. See Inserting.
You can escape four characters: asterisk (*), underscore
(_), sharp # and backslash \. When escaped,
these characters have no syntactic effect anymore. Escaping
backslashes only makes sense for the bhl2latex conversion.
When converting into LaTeX, bhl escapes some characters by
itself. These characters are: $ & % { }. Attention: the
bhl2latex conversion does NOT automatically convert
backslashes. You've to insert something like $\backslash$ by
yourself or escape them like \\. When converting into Texinfo,
bhl escapes @ { }.
If you don't want that bhl escapes those characters, just escape them by yourself in the bhl file.
There are two kinds of links: URLs and WikiNames. An URL is... you
know what it is. A WikiName is a mixed-case word like “MyWikiName”.
When the cursor is on a link, you can hit <RET> or <mouse-2>
to follow it. Following an URL calls
bhl-browse-url-function. Following a WikiName finds a new
file whose name is the concatenation of the WikiName and the
.bhl extension.
You can downcase this resulting name by setting
bhl-downcase-wikifiles-names-flag to non-nil. You can
also change the default extension of WikiFiles names by setting
bhl-default-wikifiles-extension. The list of mixed-case strings
that shouldn't be considered as WikiNames is stored in
bhl-non-wiki-names-list.
You can see the list of links of your document with bhl-show-lol, which is bound to <C-c C-/>. You can insert the list of links of your document with bhl-insert-lol, which is bound to <C-c C-c l>. See The list of links.
You can browse URLs and WikiNames with bhl-goto-next-url-or-wiki <C-TAB>. (See Browsing the BHL file.)
URLs are converted by the bhl-convert-url function and
WikiNames are converted by the bhl-convert-wiki-names
function. You can write your URL as it is (http://site.org),
or put it into square brackets to define a label:
[[http://site.org][my site]].
You can insert an URL with bhl-insert-url, <C-c C-c h>: See Commands and key bindings.
Here is a list of some URLs and their conversions into the HTML format:
|
Here is a list of some URLs and their conversions into the LaTeX format:
|
Here is a list of some URLs and their conversions into the Texinfo format:
|
Here is a list of some URLs and their conversions into the SGML format:
|
Here is a list of some URLs and their conversions into the TXT format:
|
In these examples, you can replace `http://' by `ftp://' or
`file:///'. When using [[...][...]], a prefix like `http://'
is not mandatory.
bhl handles three kinds of lists: non-ordered lists, ordered lists and descriptive (or definition) lists.
A non-ordered list item is defined by: some <TAB> at the
beginning of the line, a list separator among <- * o>, a
whitespace.
An ordered list item is defined by: some <TAB> at the beginning of the line, a number, a dot, a whitespace.
A definition list item is defined by: some <TAB> at the beginning of the line, a term, a whitespace, two dashes, a whitespace.
<TAB> inserts an indent-relative TAB, while <M-TAB> inserts a
rigid TAB mesuring exactly three columns. Make sure that there is a
whitespace after a *: no whitespace means that the next
characters may use bold font.
bhl handles also nested lists, but no definition list can be nested. To add a nested item, just add a TAB character relatively to the previous item. In each list, the first item indicates the kind: ordered, non-ordered or definition list.
Here is a table of lists separators:
<TAB(S)>[*,-,o]<SPC><TAB(S)>[0-9].<SPC><TAB(S)>A term<SPC>--<SPC>Take a look at the examples on http://www.nongnu.org/bhl for further details.
Here is an example of a table:
| @Name@ | @First name@ | @Age@ |
| Jean | Luc-Henri | 123 |
| Paul | Matthieu | 2 |
|
The character | has three different functions: it begins a new
row, it seperates two cells, it ends a row. Whitespaces and tab
characters are NOT allowed between the beginning of a new line and the
first |.
Optional @ around the cell content indicates that this cell is
a header. Typically, you put headers on the very first row of the
table. In the HTML output, a header cell is put into <TH></TH>
tags. In other LaTeX and SGML, the header line is separated from the
rest of the table by an horizontal rule.
More details about the table options: See Converting tables.
Here is an example of how to insert an image:
[[image.jpg]]
You can search for a particular file and insert it as an image with <C-c C-c i>, wich is the default key binding for bhl-insert-image.
Only bhl2html handles images. Other conversion functions like bhl2sgml, bhl2texinfo or bhl2latex put images into comment strings. bhl2txt erases images.
You may want to convert your bhl document without
customizing anything. This is OK. But you surely want to control
some properties of the different conversion functions. For example,
you may decide that the HTML conversion includes the table of
contents, whereas the LaTeX conversion doesn't. You may want to
calculate the \date{...} command of the LaTeX output
relatively to the current time. You may want to set up a different
CSS style for a particular HTML output. Etc.
This section tells you how to do this.
The two important variables for the choice of conversions properties
are bhl-xxx-conversions-list and bhl2xxx-properties-list,
where xxx is the name of the conversion. See Global options.
bhl-xxx-conversions-list includes the detailed list of conversions for each format. Normally you should not change this variable too often.
bhl2xxx-properties-list allows you to set global options for the conversion. These global options deal with the checking of dubious tags, the insertion of the sections' prefix, the tables' captions, the i18n conventions, the insertion of the table of contents and the centering of sections/title (for the bhl2txt conversion.) You can change this variable by:
This order is important: the options set inside a specification line will override the options set from the menu, which override those set in the default customization.
These global options are set to their default value (i.e. their
customized value) each time you run the bhl-mode command. They
are also set to their default value after each conversion, except if
you remove the bhl-initialize-properties function from the
bhl-after-conversion-hook list.
bhl allows you to add some specification lines inside a document, so that bhl handles this document adequately. Specifications concern mainly two kind of properties: the properties of the document's header and the conversion properties. Here are some examples of specification lines:
#!html!prefix:check:caption:toc
#!latex!noprefix:nocheck:nocaption:notoc
#!date!It's %H:%M.
In this example, the command bhl2html will insert the sections' prefix, check for dubious tags, ask for a caption for each table and insert the table of contents (also known as toc). The command bhl2latex WON'T insert the sections' prefix, check for dubious tags, ask for a caption for each table and insert the toc. The date will be set to the current time (hours:minutes). Quite simple, isn't it?
A specification line is always a comment at the beginning of the line.
It splits into two parts: a prefix, which is enclosed into two
exclamation marks, and the labels, which are separated by a
column. Each label can be turned off by adding no-:
notoc is the exact opposite of toc.
Here is a complete list of available specification prefix and their relevant labels.
#!author!#!title!#!xxx-title!
specification).
#!xxx-title!xxx conversion. xxx
may be html, sgml, texi or latex. This
specification is overriden by the #!title! specification, and
overrides the first line of the buffer.
#!subtitle!#!lang!@documentlanguage.
#!encoding!@documentencoding. In the HTML output, it overrides the
value of bhl-html-content-type.
#!date!#!date!%H:%M will set date to the current time
(hours:minutes). see Time Conversion.
#!html!prefixcheckcaptioni18ntoc#!html-style!#!latex!prefixcheckcaptioni18ntoc!#latex-class!#!latex-options!#!latex-packages!
#!latex-packages!fontenc[T1]:[latin1]inputenc:babel[french]
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage[french]{babel}
The location of the square brackets doesn't matter.
#!texi!checki18ntoc#!texi-style!classical or centered.
#!sgml!checkcaptioni18n#!txt!centertoctas
The bhl mode comes with two commands that allows you to
browse your document: bhl-show-toc and
bhl-show-lol. The latter is not a joke: it allows you to
browse the list of links. The former allows you to browse the table
of contents. These two commands create a new buffer turned into
either bhl-toc-mode or bhl-lol-mode.
The bhl mode enables you to update the numbering of sections of your bhl file, to insert the table of contents into your bhl file, to browse the table of contents in a new buffer.
Two variables are required to handle the table of contents: bhl-toc-location and bhl-default-toc-depth. The first one defines the location of the inserted toc. You can change its value via the menu or via customize. The second one defines the default toc depth.
You can insert the toc with bhl-insert-toc <C-c C-c
t>. A numeric argument defines the depth of this inserted toc. You
can also insert the toc from the *toc* buffer with <i>.
From this buffer, the toc depth is set to the depth of the currently
displayed toc.
When it converts the buffer, bhl first checks if there is a table of contents. If there is one, bhl inserts it in the output according to the current toc location of the buffer.
You can get a new buffer, named *toc*, with a browsable table
of contents. You can browse the toc via the menu or with the key
binding <C-c C-t>. An optional numeric argument indicates the toc
depth.
bhl-toc-mode.
*toc* buffer.
You can insert the table of contents of your bhl file into itself with <C-c C-c t>. If a toc has already been inserted, this command only updates the table of contents, leaving it to its current location. If a toc has not been inserted yet, this command inserts a new one according to the value of bhl-toc-location. An optional numeric argument indicates the toc depth.
You can see the list of links with bhl-show-lol. The
default key for this command is <C-c C-/>. A new buffer is
created, named *lol* and turned into the bhl-lol-mode.
While moving inside this buffer, your document's buffer is updated so that its point is set to the link you're currently pointing on. You can also visit the link you're pointing on with <RET> or <mouse-2>.
Here is a list of the available commands inside the
bhl-lol-mode:
bhl-lol-mode.
*lol* buffer.
This section describes the main commands of the bhl mode.
This conversion commands end with two hooks: a hook relative to each conversion format (bhl-xxx-after-conversion-hook) and a global hook (bhl-after-conversion-hook). You can also reach these commands from the popup menu <C-down-mouse-3>: press <control> and the right button of the mouse.
Convert the current buffer into HTML and display the output in a new buffer. The default key binding is <C-c C-w>.
Convert the current buffer into LaTeX and display the output in a new buffer. The default key binding is <C-c C-l>.
Convert the current buffer into Texinfo and display the output in a new buffer. The default key binding is <C-c C-o>.
Convert the current buffer into SGML (Linuxdoc) and display the output in a new buffer. The default key binding is <C-c C-s>.
Convert the current buffer into (kind of) WIKI and display the output in a new buffer. Strip the remaining tags and syntaxic elements. The default key binding is <C-c C-k>.
Convert the current buffer into TXT and display the output in a new buffer. Strip the remaining tags and syntaxic elements. The default key binding is <C-c C-d>.
Read an URL and his name from the minibuffer and insert it. The default key binding is <C-c C-c h>.
Read the filename of an image from the minibuffer and insert it. The default key binding is <C-c C-c i>.
Insert a verbatim environment. The default key binding is <C-c C-c v>.
Insert a horizontal rule. Ask for its alignment and width in the minibuffer. The default key binding is <C-c C-c r>.
Insert the table of contents into the current buffer. The default key binding is <C-c C-c t>. This command is also available from the
*toc*buffer in bhl-toc-mode with <i>.The optional argument (
depth) indicates the toc depth. Without any argument, the toc depth's value is bhl-default-toc-depth.You can insert the table of contents in three different places: just after the title, just before the end, just at the point. The value of bhl-toc-location defines the toc location.
Insert the list of links into the current buffer. The default key binding is <C-c C-c l>. This command is also available from the
*lol*buffer in bhl-lol-mode with <i>.
Get a new buffer named
*toc*with the table of contents. The default key binding is <C-c C-t>. The optional argument (depth) indicates the toc depth. Without any argument, the toc depth's value is bhl-default-toc-depth. This command is also available from the popup menu.
Get a new buffer named
*lol*with the list of links. A link may be an URL or a WikiName. The default key binding is <C-c C-/>. This command is also available from the popup menu.
Go to the next section. The default key binding is <C-c C-n>. With <C-u>, go to the next section or (sub)subsection.
Go to the previous section. The default key binding is <C-c C-p>. With <C-u>, go to the previous section or (sub)subsection.
Go to the next URL or WikiName. The default key binding is <C-TAB>.
Place the cursor between two
*. If a region is selected, put the region between two*. This overrides previous fontification. The default key binding is <C-c C-f C-b>.
Place the cursor between two
_. If a region is selected, put the region between two_. This overrides previous fontification. The default key binding is <C-c C-f C-e>.
Place the cursor between two
__. If a region is selected, put the region between two__. This overrides previous fontification. The default key binding is <C-c C-f C-u>.
Place the cursor or a selected region between two
==. If a region is selected, put the region between two==. This overrides previous fontification. The default key binding is <C-c C-f C-t>.
Place the cursor between
_*and*_. If a region is selected, put the region between_*and*_. This overrides previous fontification. The default key binding is <C-c C-f C-_>.
Strip any fontification of the selected region. No effect when no region is selected. The default key binding is <C-c C-f C-n>.
Read a sectioning style from the minibuffer and convert (sub)sections' prefix into this style. The available styles are
num,alpha,asterandequal-sign.
Comment the current region. With a symbolic argument, uncomment the current region. The default key binding is <C-c ;>.
Make the comments invisible. With a symbolic argument, make the comments visible again.
Convert the current buffer into TXT format with bhl2txt and use the output in a mail draft. The default key binding is <C-c C-x m>. This command is also available from the popup menu.
Update the sections', subsections' and subsubsections' numbering. The default key binding is <C-c M-t>.
Send a mail with a bug report. This is only available in GNU Emacs.
Display the version number of the bhl mode. The default key binding is <C-c C-v>.
Toggle accents in a Texinfo buffer. If you are using accents, it may be a good idea to add this function to bhl-after-texi-conversion-hook.
You can change the value of each option via M-x customize-group RET bhl RET or via Customize BHL in the bhl menu.
Hook run while in bhl mode. If you are under GNU Emacs, it could be useful to add
footnote-mode, since bhl converts footnotes.
Hook run at the very end of a conversion. The default value is bhl-initialize-properties. If you remove this function, the conversion properties of the last converted buffer will be the default conversion properties for the next converted buffer – which may not be what tou really want.
If non-nil, autoguess the sectioning style. When you find a file, BHL tries to guess its sectioning style and sets the value of `bhl-sectioning-default-style' to the value of the file's style.
The default value of bhl-autoguess-style-flag is
nil.
Define the style for the titles of sections, subsections and subsubsections. The five available styles are: numerical (
num), alphabetical (alpha), asterisks (aster), equal-signs (equal-signs) and your own style (my). See Sections.If you want to use your own style, you have to define bhl-my-sectioning-regexp-list. In this case, bhl-update-toc is not available anymore.
A list of regular expressions that match the different levels of sectioning. They respectively match the prefix of a section's, subsection's and subsubsection's title. Since the titles of the sections are always put at the beginning of the line, you don't have to insert a
^in these regular expressions.The default value of bhl-my-sectioning-regexp-list is the value of bhl-my-sectioning-regexp-list, which corresponds to the numerical style (
num)..
A list of syntactic elements that shouldn't be converted when found inside a verbatim environment. The default value of this variable is
(tag comment list description table url wikiname images special-char tex-label footnote quote).
A list of regexps. Each line matching a regexp within this list is automatically killed before any conversion.
Non-nil means that you can use tags on multiple lines. Maybe useful to turn this option off is you want to use tags on multiple lines inside a verbatim environment.
The car of this variable is a language specification among
english,frenchandgerman. bhl will follows conventions according to the chosen language.If the second element if t, bhl follows conventions concerning the punctuation, as defined in bhl-xx-punctuation (where
xxisen,frorde).If the third element if t, bhl follows conventions concerning the quotation marks, as defined in bhl-xx-quotation-marks.
If the fourth element if t, bhl follows conventions concerning special characters, as defined in bhl-xx-special-chars.
A function for calling your favorite browser. The default value is browse-url.
The list of properties relevant for the bhl2html conversion. See Properties of conversion. Don't modifiy this variable manually. Use
M-x customizeinstead.
A list of conversions to perform with bhl2html. Each element of this list is boolean. Don't edit this option manually, use M-x customize instead.
A list of META tags to be inserted in the header of HTML output. Each element is divided into two elements: the first one indicates the name of the META tag, the second one indicates the content of the META tag.
'((``author'' . ``you''))<META name="author" content="you">
A list of
LINKtags to be inserted in the header of HTML output. Each element is divided into two elements: the first one indicates the rel of theLINKtag, the second one indicates thehrefof theLINKtag.
'((``generator-home . ``http://www.nongnu.org/bhl))<LINK rel="generator-home" href="http://www.nongnu.org/bhl">
The document type description of the HTML output. The default value is:
<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\">.
The content type description of the HTML output. The default value is:
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1>".
The style to be inserted into the header (
<HEAD>...</HEAD>) of the HTML output.
A list defining the opening and closing tags of the HTML subtitle.
How bhl aligns each paragraph of the HTML output. The default value is
none.
Non-
nilmeans that list items are paragraphs into the HTML output.
The list of properties relevant for the bhl2latex conversion. See Properties of conversion. Don't modifiy this variable manually. Use
M-x customizeinstead.
A list of conversions to perform with bhl2latex. Each element of this list is boolean. Don't edit this option manually, use M-x customize instead.
A list of packages to be included in the LaTeX header. Each element is divided into two elements: the first one indicates the name of the packages, the second one indicates the options of the package.
- '((``inputenc'' . ``latin1''))
\usepackage[latin1]{inputenc}.
The default class of document for the LaTeX output. The default value is
article.
The default options passed to the
\documentclass{...}command. The default value is12pt.
The default options passed to the
\documentclass{...}command. The default value is12pt.
Hook run after the Texinfo conversion. The default value is
(texinfo-every-node-update bhl-texi-make-menu), so that the output file is ready for compilation. If you are using accents, you may addbhl-texi-toggle-accents.
The list of properties relevant for the bhl2texinfo conversion. See Properties of conversion. Don't modifiy this variable manually. Use
M-x customizeinstead.
A list of conversions to perform with bhl2texinfo. Each element of this list is boolean. Don't edit this option manually, use M-x customize instead.
Set the
@setchapternewpagevalue. The default value ison.
The style of the title page. The
classicaltitlepage is the one mostly used by the GNU manuals. Thecenteredtitlepage centers the title and other informations on the front page.
The default tag used for the conversion of centered minipages. See Environments.
The tag for the conversion of tables in the Texinfo output. The default value is
verbatim. If you want to skip tables when converting into Texinfo format, you should set this toignore.
The list of properties relevant for the bhl2hsgml conversion. See Properties of conversion. Don't modifiy this variable manually. Use
M-x customizeinstead.
A list of conversions to perform with bhl2sgml. Each element of this list is boolean. Don't edit this option manually, use M-x customize instead.
Non-
nilmeans that list items are paragraphs into the SGML output.
The default tag used for the conversion of minipages. See Environments.
Starting with 1.7.9, BHL implements a bhl2wiki
fonction. For now, the conversion is far from perfect, but it may be
useful.
Hook run after the conversion into WIKI. This hook is run just before `bhl-after-conversion-hook'.
A list of conversion functions to perform with `bhl2html'. Each element of this list corresponds to a conversion function.
The list of properties relevant for the bhl2txt conversion. See Properties of conversion. Don't modifiy this variable manually. Use
M-x customizeinstead.
A list of conversions to perform with bhl2txt. Each element of this list is boolean. Don't edit this option manually, use M-x customize instead.
If non-
nil, this means that bhl is a local wiki. You can toggle this variable from the menu.
The default extension for the Wiki file names. The default value for this options is
.bhl. For example, when following a WikiName namedMyWikiName, a new file namedMyWikiName.bhlwill be found.
If non-
nil, following a WikiName namedMyWikiNamewill find a file namedmywikiname.bhl, which is the downcased value of the WikiName. Otherwise, it will find a file namedMyWikiName.bhl.
A list of mixed-case strings that should not be considered as WikiNames. For example: “OpenOffice”.
Indicates the toc location. This variable may have three different values:
top(just after the title),bottom(just before the end) orpoint(at point).
Where to put the table. The default value is
htbp, i.e.here top bottom page. This variable does not concern the HTML output.
Just ANother Example
--- Table of contents
1. Fonts and environments
1.1. Using font beautifiers
1.2. Environments
2. Converting lists
2.1. Ordered and non-ordered lists
2.2. Description lists
2.3. Nested lists
3. Converting tables
4. Browsing your document
4.1. The table of content
4.2. The list of links
5. Contact
--- End of the table of contents
# This is the last example of a BHL file converted into HTML, LaTeX
# and SGML formats. This example shows you the various syntaxic rules
# that BHL handles. For further details, please refer to the manual
# of the BHL mode. http://www.nongnu.org/bhl
# These lines are comments.
# You can comment a region with `bhl-comment-region'
# The few next lines are specification lines. They
# indicate the properties of the different conversions.
#!author!Bastien Guerry
#!date!It is %Hh%M on %d/%m/%Y.
#!html!toc:nocaption:noprefix:noi18n
#!sgml!caption
#!latex!toc:caption:prefix:i18n
#!latex-options!11pt:a4paper
#!latex-packages!inputenc[latin1]
This document is a small example of what BHL can do. For further
details, please read the full documentation on
http://www.nongnu.org/bhl.
#!language!fr
#!encoding!iso-8859-1
#!texi-style!centered
1. Fonts and environments
1.1. Using font beautifiers
Here is a list of the *different* fonts beautifiers that you can
use inside the BHL mode.
Bold -- *one or two words.*
Emphasis -- _one or two words._
Truetype -- ==one or two words.==
Underline -- __one or two words.__
Bold italic -- _*one or two words*_.
If want to insert an asterisk, you can use the escape character like
\*this\* or like \_this\_. This is also available for \#comments.
1.2. Environments
BHL handles two specific environments: verbatim and minipage.
Verbatim:
--
Here is a *part* of text that will be displayed
in verbatim #a comment
Please remark[1] that this environment has no syntactic rule, except
you modify the variable bhl-verbatim-ignore.
* list are ignored
And so do...
Item -- descriptions.
And so do tables!
| A | B |
| C | D |
And so do quote environments:
blahblahblah
blahblahblah
Etc.
--
A minipage:
%%%[12cm]
This minipage (12cm) is centered without border.
%%%
<%%[10cm]
This minipage (10cm) is put on the left without border.
%%%
>-%[8cm]
This minipage (8cm) is put on the right with border.
%%%
A horizontal rule:
----[3cm]
Another horizontal rule, put on the right:
>---[3cm]
2. Converting lists
2.1. Ordered and non-ordered lists
*Ordered* lists begin with three *whitespaces*, a list separator (\*, - or o)
and another whitespace.
* Like this;
* or like that.
2.2. Description lists
Description lists are treated like other lists, except that they
cannot be nested in other lists.
A description item consists in tabs, a term to be defined, a
whitespace, two dashes and another whitespace.
Term -- a definition of the terme.
Definition -- another definition.
2.3. Nested lists
* Lists can be nested inside other lists.
* You just need to add three whitespaces more.
* These to items will be nested into two other items. sldkfj
lskdjf lmmlkm
1. Three levels of nested lists are supported.
2. Four levels won't be very useful...
* Blank lines are not mandatory between items.
3. Converting tables
A WikiName.
Here is a table:
| @dHL et lqskdj@ | @qsdqsdOolsqdf@ |
| Free softxware | bastien1@free.fr |
| With Emacs | Without Emacs |
| bastien | Without Emacs |
A table line begins and ends with a "|". Other "|" inside a line of
the table separate two cells. Arobases around the content of a cell
mean that this cell is a header of the table.
4. Browsing your document
4.1. The table of content
You can _browse_ the table of content, _insert_ it inside your
document, and _update_ the numbering of sections.
The default key binding for browsing the table of content is C-c
C-t.
You can also choose the style of sectioning and swith from one style
to another. The style of this document is set to *num* (which is the
default style) by the specification line above.
4.2. The list of links
The default key binding for browsing the list of links is C-c
C-/. This creates a new buffer with a list of URLs or wikinames that
you can follow.
5. Contact
Please feel free to submit bugs or ideas:
[[mailto:bastien1@free.fr][BHL contact]].
Footnotes:
[1] A note.
BHL is somewhat related to emacs-wiki.el and
muse.el and you should have a look at them. They are more
wiki-oriented than BHL and they can be more convenient if
you want to convert a lot of pages at the same time. But basically
they do the same job.
Thanks to Serge Basterot, Jeffrey Borlik, Christoph Conrad, Tim Cross, Mario Domgörgen, Thomas Gehrlein, Jacob Hamacher, Sylvain Holtzer, Dan P. Katz, Mario Lang, Massimiliano Mirra, Julie Neveux, John Stauffer, Thierry Stoehr and Marco Testi.