A2E::MLHT
Generate files in several languages from one multilingual template, using =over =item static variable lists generated by the (dynamic) means of the maketext syntax described in A2E::Tmplfil and A2E::SArb::Make =item reactivate dynamic variables and fill the with values using the Textbau filter implemented in A2E::Template::Plugin::Textbau =back
A2E::Dokfs(3)
A2E::Valid(3)
SDBM_Fileet al
Whether to collect initial vocabulary from a pre-compiled DBM file. Normally we rebuild it from the sources that fit the document type (tmpl).
Used by function dok_set_tmplvars.
whether we are working on a 'dok' or a 'nav' document. deprecated, for internal use only.
Configuration parameters for the templates used for creation of makefile, navigation file, main document etc.
general configuration
/etc/opt/a2e/mlht.konfand site-specific configuration, loaded depending on --daba value
/etc/opt/a2e/mlht_a2e.konf
/etc/opt/a2e/mlht_ffii.konfas well as user-specific additions
~/mlht.konf
~/mlht_ffii.konf
~/mlht_a2e.konfand document specific configuration files
./mlht.konf
@mlht A2E::Template::Plugin::Textbau
tmplfil(1)Lightweight version of doks2reks, possibly now obsolete.
Return a list of hashrefs, each having fields dok, url and lab, which contain the info needed for a navigation menu. Subroutine of vmethods predokreks, postdokreks, subdokreks
Define some extensions of the mlht maketext (A2E::SArb::Make) language to be used in text chunk files, such as tit in
text1 := The title of oas_varb0904 is $(tit:oas_varb0904)See also &A2E::Template::Context::defin_tmplfuns More generic methods/filters/blocks that are independent of the A2E::Dokfs application layer should go there.
Turn a list variable from the maketext language into a list variable that can be used by the Template language.
Example:
If antevar is defined in the maketext file
deflst chunks
lstpucq chunks mm
lstpucq chunks aamm
lstpucq chunks temas defined by A2E::Tmplfil, then a template text
[* FOREACH var = 'chunks'.nom2xlst -*]
- [* var *]
[* END -*]leads to an output of
- mm
- aamm
- temThe list variable can be quite complex. Lower layers need not be lists but can be hashes or strings or references to variables of such types.
Same as nom2xlst but for hashes.
Validate a lit (template variable) here and now, using the validation information given through some special lits.
TODO: migrate the specification of those special lits to more robust structured variables such as __valids__, __errmsg__ etc which are internally created and appended using defxhac, hacxput etc.
When used in maketext
special upon_setvar sems set_semsor in A2E::Txtdbm, it ensures that the information from textchunk sems, as soon as it set, is analysed and registered internally, so that __sem1, __sem2, __sems etc are set and the sems itself will not be changed again.
args :=
rets := ok
ok :: true if operation was achieved i.e. with sems was non-null and usable
Read in document configuration $m->{dok} must have been set before.
set some special, language-independent variables
Allow handover of parsed tree variables via the stash to external systems like A2E::Template::Plugin::Call:
m->{SArb}->{vars} = context->{STASH};
m->{SArb}->{arbs} = context->{STASH}->{__ARBS__};Give a file name of a dbm database file and return a hashref containing all the template variables of that document.
Optional arguments %opts can be submitted in hash form:
tmplvars => { tmpl => 'pub_aamm', dokdatum => '2015-03-21' }
an initial vocabulary hashref
This can however not be used for writing anything into the DBM file.
kiifilter => sub { shift =~ m(\AnextQ7\_); }
keyfilter closure function that specifies a filtering condition working on the name of the variable, e.g. the example value
would accept only variables that begin with nextQ7_ (name of a subdocument) into the vocabulary hashref.
force => 1
force reading from _pre.*.txt files if the specified dbm file is not presentGive an identifier of a quoted document and return true if all the template variables of that document were collected. An optional second argument is the language. Further arguments can be passed as options to dbm2tmplvars.
SET_LANG: If no language argument is given, we check whether the quoted document is available in our current language. If this is the case we choose the current language, otherwise the source language of the quoted document.
set $m->{tmplvars} for one language and do postprocessing.
set template variables
Read template variables from dbm file where possible and otherwise from textchunk files.
In the latter case, '_pre.$dok.txt' is read initially so as to determine the document type 'tmpl' and thereby the template_include_path.
Arguments: $dok: document, $lang: language. If $lang is missing, do not read language-specific textchunk files. If $dok is missing, assume current $m->{dok} in current directory.
used by A2E::MKtdir and A2E::MakefileCache
Write a file from a template
args := fi, fo, var+
fi :: template file
fo :: output file
var :: key and value of an emacs file local variable to be used
a special key 'tmplkonf' can be used to pass a hashref of options such as TAG_STYLE to the template
a special key 'lokvars' can be used to pass a listref of emacs local variables to be used
a special key 'mode' can be used to suggest a way of chosing $stag and $etag for comment expressionssubroutine for processing arguments of litscat, but with more potential use.
args := arg, litstem, varnom, listlevel, priv?
rets := arg
arg => [ '1', [ '&', 'q', 'a' ], '_', 'a' ]
arg => [ [ 'proc', 'alineas' ], [ 'call', 'ln' ] ], 'top'
arg := listref or string, depending on listlevel
arg :: value of the argument, produced in litscat by 'shift' while parsing the commandline and enhanced by us
litstem => 'top'
litstem :: stem of stash variable
varnom => 'jungils'
varnom => 'priv'
varnom :: name of variable to be underscore-joined to stem and searched in stash
listlevel :: level of listification (use of chainsplit) leading to a more or less complex return value
listlevel 0 :: string
listlevel 1 :: simple listref
listlevel 2 :: listref of elements of which splittable ones become listrefs, others scalar
listlevel 3 :: listref of listrefsConstruct hierarchy and typesetting rules of a document based on naming of text chunks found in database (lits) and typeset (cat) the document.
args := litstem, kontils, jungils, litlvl, litnum
litstem :: stem of top level text chunk names
litstem => 'top'
kontils := listref of strings or listrefs
kontils :: counters to be used
kontils => [ '1', [ 'q', 'a' ], '1' ]
jungils := listref of listrefs
jungils :: joiners to be used
jungils => [ [ 'proc', 'alineas' ], [ 'proc', 'qeta' ], [ 'call', 'al' ], [ 'call', 'ln' ] ]
litlvl := integer
litlvl := sectioning level of any subsectional chunks (sublits), default 0
litlvl => 0
litnum := integer
litnum :: sequential number of current lit
litnum => 0
Of these, kontils is no longer used in the new implicit naming syntax described in dok:adv_pub_litscat1004. Also, in the case of implicit naming, jungils is preferably read from the internal variables such as '_top_jungils' in every group by &A2E::Tmplfil::tmplvars_opengrup.
A call like
$m->litscat('top', [ '1', [ 'q', 'a' ], '1' ], [ [ 'proc', 'al' ], [ 'proc', 'qeta' ], [ 'call', 'al' ], [ 'call', 'ln' ] ], 0)should ensure that text chunks implicitely named with
(q8a /proc+al/proc+qeta/call+al/call+ln/
(intro
(q8a_q
...
)
(q8a_a
(
this is line a of paragraph 1 of A part of the intro section of our Q&A
this is line b of paragraph 1 of A part of the intro section of our Q&A
)
)
)
)are typeset based on the definitions in template language of
block alineas
block qetaand definitions in maketext language of
chunk al
chunk ln
where block qeta is a user-defined template language block named 'qeta', and 'al' and 'ln' are user-defined 'call'able verbs, and all of these elements are fed with the text chunks that belong to their level.
The joiners (e.g. 'proc+qeta', 'call+al') can be reset for any element at any level by saying, in the textchunk file, e.g.
(q8a
...
(
( |call+lnol|call+ln|
)
)
)meaning that within the question part of block 2 we use 'lnol' for concatenation at the first level and ln for concatenation at the next level.
Joiners used most are proc and call, also in conjunction with revargs, e.g.
des5_jungils := |revargs:1:proc:desclist&tagdesc_regex&\A(\w+)\s\:\:\s(.*)\Z|call:al|call:ln|where revargs (reverse arguments) assures that textchunks are counted downwards, which might be useful in a chronological list, see example below.
Note that parameters passed to proc (equivalent template process statement) must in this case be all contained in a single argument together with the command verb itself so as not to interfere with the argument count of revargs. In the above example this single argument uses '&' as its internal separator, because most others are blocked by the letters that appear in the regexp. It might be more elegant to write
desclist_regexp = \A(\w+)\s\:\:\s(.*)\Z
des5_jungils := |revargs:0:proc:desclist+tagdesc_regex+${desclist_regexp}|call:al|call:ln|The numeric argument or revargs indicates how many initial list elements are exempted from the reversal. This can be useful in case of sections like
log0 = Chronology
log1 = 2009-03-01 first event
log2 = 2009-03-02 second eventwhere we want a reverse chronology of events but a subject line ("Chronology") coming first in any case. The 'revargs' function is similar but unrelated to the 'revargs' function of text textchunk language.
The 'revargs' function has become less important in the new system of implicit naming.
Allowable counters in the old syntax were:
'1' : /[0-9]+/ : any arabic number, decimal system, starting from from number indicated here
'a' : /[a-z]+/ : any alphabetic number, eicosahexesimal ($ALPHA_BASIS-based) system with 'z' as 0, 'a' as 1 and 'az' as 26, starting from the alphabetic number indicated here
'nom+des+rev+img' : enumerated set of new stems
'++1+2+2a+2b' : enumerated set of suffixes attached to existing stem
'++a..c+e..h' : enumerated as above, with ranges (e.g. here leaving out 'd' even if it exists and going up to 'h' even if not every one of these exists)
'++1..3+5..8' : enumerated as above, with ranges (e.g. here leaving out '4' even if it exists and going up to '8' even if not every one of these exists); TODO: ensure that this is implemented
'_' : underscore separator between levels, needed when counters take forms like '+1+2+2a+2b'In the new syntax counting is always done implicitely has no choice regarding the numbers and formats used. Where this is a problem, the solution is to be sought at the level of Template programming using mechanisms such as the one sketched by 'tagdesc_regex' above, which is supported in our 'desclist' block definition in 'bautext_tmpl.txt'.
Any template language blocks invoked in the jungils argument have the following template variables available for their use:
litvals := list of strings
litvals :: evaluated chunks of text to be concatenated by the block
litstem := symbol
litstem :: stem name of the block, usable e.g. as an anchor name
litlvl := integer
litlvl :: hierarchy level of the block, usable e.g. for generating a section heading
indlvl := integer
indlvl :: indentation level of the block, whis is incremented when the block is one of those set true in a hash variable such as %indproc = ||enumlist2|1||itemlist2|1||ilinioi2|1|, as demonstrated in a2e document nitaO2_pat
litnum := integer
litnum :: ordinal number of the block within the sequence of peer blocks at litlvl, usable e.g. for generating numbered section titlesMoreover, for debugging purposes, at the moment we hand the following info to each template process:
jungnom => desclist
jungnom := symbol
jungnom :: name of current joining function
jungkont => 133
jungkont := integer
jungkont :: frequency of invocation of jungnom so farComplex information such as jungils is passed by means of a structured represenation such as
proc+alineas,call+ln # wrong syntax
,proc+alineas,call+ln
/proc+alineas/call+ln/in which the separators can be chosen freely but the higher-level separator must come before the lower-level separator. The second and third of the above three examples will work, the first not.