This describes version 0.1.6


a2e multilingual hypertext file system library, used by many small programs, based on A2E::Daba and A2E::Lokvars, basis for A2E::Mktdir::* et al.

This "file system" is an abstraction layer on top of normal file systems. It should allow you to perform operations such as change, move, copy, delete etc on whole document nodes which comprise a rich set of metadata, rather just on files and directories.

It is a successor of the A2E::Dokfs library and thus already quite mature at version 0.0.1.


Search for 'BUGS' statements in some functions.


allow setting of srcfpfx in each directory

Functions like dok_pre_lng_faylz and rmdok should use whatever prefix is found to be in use in the concerned directory.

The same heuristics should be used to determine MPX in a2e/ and the like.


using the get_dok_plugins approach, retain only core functionality, move major parts out into mix-in libraries, built along the model of A2E::Lokvars. Turn the Mktdir libraries into mix-in libraries of this type.


Use Tinymake or the like to incorporate the makefile rules that are part of document creation. Turn calls of standalone programs into function calls.

Consider combination with Psh to create a Dokfs shell.

Real Alias Mechanism

The document alias should be registered in a separate table with proper constraints, not in doktexts.





This describes version 0.1.6 of A2E::Dokfs.


--dok oas_ont0812
--langs en --langs de --langs fr
--lifmt '%s'
--unifnom '%ptop-%d.%l.txt'
--mulfnom '%pdok.%d.%l.txt'
--lexfnom '%plng.%d.%l.txt'
--lexfnom0 '%plng.%d.txt'

Multilingual vocabulary lng.perllibdoku.txt should come before monolingual vocabulary

Traditionally it was the other way around. Starting from version 0.4.5 this is set to 1 in the local configuration file dokfs

--antefnom0 '%ppre.%d.txt'

File with lexical definitions that come before anything else. Suitable especially for numeric parameters on which decisions in templates and template vocabulary files are then based.

--antefnom '%ppre.%d.%l.txt'

File with lexical definitions that come before anything else. Suitable especially for numeric parameters on which decisions in templates and template vocabulary files are then based.

--post_lexdef_fmt 'unexport %s := %s'

default format of lexical definitions in the language neutral vocabulary file read at the end, using printf syntax with two arguments: variable name and variable value.

--ante_lexdef_fmt '%s ?= %s'

default format of lexical definitions in a pre-definition vocabulary file, using printf syntax with two arguments: variable name and variable value.

--doktmplfnom 'dok_tmpl.txt'
--tmplngantefnom0 'lang_pre.txt'

file naming template for template-related non-language-specific pre-vocabulary file

--tmplngantefnom 'lang_pre.%l.txt'

file naming template for template-related non-language-specific pre-vocabulary file

--tmplnglangfnom 'lang.%l.txt'

file naming template for template-related language-specific vocabulary file

--tmplngpostfnom 'lang.txt'

file naming template for template-related non-language-specific post-vocabulary file. Placeholder 1 is the language.

--konf_tmpl_fnom %t_konf_tmpl.txt

filename format for configuration files templates, arg1 to be filled by $m->{tmpl}. This is appended to $m->{topdir}/$m->{topdok}_ or, when installing the latter, ${tmpldir}

--primdir /srv/www/a2e

regexps for matching 'sig_oas1312' into ('oas', '13', '12') whence '/sig/oas/13/12'

--html_suffix html

Using the dirurls variable and its inversion dirurls, we try to have as simple as possible mappings between the web path and the file system path on the one hand and the SVN path and file system path on the other: -->  /sig/i2p/07/10    <-- /svn/sig_i2p0710/    -->  /a2e/index.html   <-- /svn/a2e/index.html -->  /eupat/07/10      <-- /svn/eupat0710

inversion, derived from urldirs but can also be set manually.


inversion, derived from vihdoms but can also be set manually


inversion, is derived from urldirs but can also be set manually.


several ways of recognising a document, insertable and removable.


Date of the current document, in '2008-08-08' style notation. This should be the an unequivocal and largely immutable attribute, such as date of creation, the deadline of delivery. The value of the 'dokdatum' configuration variable can be overridden by the value of a template variable named 'dokdatum' or by the value of a template variable named by the value of a template variable named 'dokdatum_var'.


Date of latest version of (i.e. latest changes to) the current document.


news/rss channel from which the current document publishes news, scalar but with possibility of indicating several, separated by commas or spaces

--putkanals oas_adv,adv:-1

news/rss channels into which the current document is inserted as a news item, scalar but with possibility of indicating several, separated by commas or spaces, and a possibility of attaching, after a colon, a degree of importance to each, with 0 representing normalcy and positive or negative integers representing increased or decreased degrees of importance respectively.

--news_start 2008-08-01

print only news items whose date is not earlier than the date given here. print even the earliest items if no date is specified.

--news_stop 2008-09-01

print only news items whose date is smaller (at least 1 day earlier) than the date given here. print everything up to now if not specified.


Print maximally this number of documents per channel.

No limit if set to zero, which is the default.

--news_level 3

Print only news items with priority level as indicated or higher.

When comparing, subtract 1 if the date is not of the current month, 2 if not of the current year.

Premium news have a rank of 3 when they are emitted. Setting news_level to 3 would mean that only premium news of the current month are allowed in this channel.

To set the level of importance of a particular news item use the --putkanals option.

--grpdir .

OBSOLETE, now dynamic textchunk sems2subflat. Node group directory. Let the document be subordinate not to the node in its normal parent directory but to the node of the parallel directory indicated by the argument. The node group directory can be the current directory '.', in which case the document is created in a parallel directory under the parent directory. If the grpdir argument is empty, the document will be subordinate to the current document in the normal way, i.e. as a subdirectory.


To which document the headline of a particular channel should link


Which template variable should be used for the title of a particular channel

--news_title_varnom0 news_tit
--news_title_varfnom %s_news_tit

Which template variable should be used for the description of a particular channel

--news_descr_varfnom '%s_news_des'
--news_limits oas_adv 5

Limit of number of news items in a particular channel

--news_levels oas_pub 1 --news_levels oas_adv -1

Threshold of news for a particular channel

--news_starts oas_adv 2009-03-01 --news_starts oas_pub 2009-01-01

date at which the news of a particular channel should begin

--news_stops oas_adv 2009-03-31 --news_stops oas_pub 2009-12-31

dte before which the news of a particular channel should end


format of name of rss file with args dok and lang

--news_kanal oas_akt

Establish the named document as a news channel. If the name is '1' or '*', use the current document identifier. If the name is '0' or empty, to not establish a news channel.

--news_kanalrem 'jeder Auftrag eine Nachricht'
--news_supkanal oas

superordinate channel -- ancestor of which the current channel becomes a subordinate

--news_kanaldat 2009-03-14

date of establishment of channel


database tables in which a document (dok) is referenced


name of field within each table that references dok, if it is not called 'dok'.

--subopts grpdir=. --subopts dokdatum=2009-04-30

Any subdocument will have the given scalar configuration variable set. Do not set --subopts tmpl, use subtmpl instead.

--dynavars dok='adv_${1}${aamm}$(or,${2},${dd})' --dynavars dir='${1}$(or,${2},${dd})'

A way to specify in a local configuration file how the (simplified and restricted for a context) commandline should be read and transformed into internal variables, using the syntax of the mlht language. Experimental, see dok:tmpl090317

Never used, probably OBSOLETE.


Cache in memory any document data of any documents referenced in the text via dok2data. The speed gain will be worth the memory increase only when the documents are referenced repeatedly. On by default but it might be sensible to turn it off in the local configuration file of certain nodes.

--supdok_non_tmplvars supdok_non_tmplvars mktdir_user=1 --supdok_non_tmplvars mktdir_time=1

text chunks that are not used as template variables when they come from an external document's vocabulary database (e.g. the parent of the actual document that we are creating with A2E::MKtdir).

Probably OBSOLETE.

--svn_root '\/\S*\bsvn'

regex matching the part of each pathname under which the subversion repository trees on the local harddisk begin. it is assumed to be surrounded by \A and \b, i.e. begin at the beginning of the pathname and end at a word border. This is consulted only in the rare cases where info cannot be directly collected from the local svn repository via the svn_info function, e.g. in cases where an application is run by Apache under identity of a user that has no svn access.

Deprecated, use textchunks of same names in @pre.$dok.txt or, even better, lang_pre.txt of document type instead.

--inddok a2e

top-level document of current web host where sitemap index is to be found. used by mktdir when creating a new top node, by sitemap_tmplfil when compiling a sitemap, and by the top node sitemap index form.

--nlangkols 1

Maximal number of language columns juxtaposed to each other in the generated document. Default is 1, meaning that all resulting documents are monolingual.

E.g. if nlangkols is 2 and the documents languages are de en zh ja, then we get one monolingual original and 3 bilingual versions:

        de en
        de zh
        de ja

If nlangkols is 3, we get

        de en
        de en zh
        de en ja

1 monolingual, 1 two-column bilingual and 2 three-column trilingual versions.

This will work together with the litscat template macro of A2E::Template::Context, which in turn will invoke special macros like



so as to typeset text parts of each level in the specifically appropriate way, resulting in something like

        * Chemische Verbindungen --- Chemical Compounds

        | Karbide | Carbides | 碳化物 |
        | Karbonate | Carbonates | 碳酸化合物 |

To make this work we create a hash pointer $m->{lang_tmplvars} which contains the language variables of several languages and make $m->{tmplvars} point to $m->{lang_tmplvars}->[$lang] where $lang refers to the current language. This has been tentatively done in &A2E::MLHT::mlht_set_langvars.

Debugging Options


Whether the tmpltoks extension that will allow multilingual metadata to be written into a special table like 'flddes' is enabled yet. Set this on for debugging only at the moment.


Whether the poorly understood idelits accumulation functionality is to be used.

It is used only in A2E::Dok2data, see explanations listref idelits.

--smprior_min 0.5

Minimal smprior (search machine priority, two digit rational between 0 and 1) needed for a news item to be listed.


configuration: _dokfs, ~/dokfs.konf, /etc/opt/a2e/dokfs.konf




    Hartmut Pilch


    Copyright (c) 2007-8 Hartmut Pilch (phm)

    This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.


Overloadable functions

Function defvars

Function insert_get_dok_plugin

Function dokfs_lastkonfig

Function lastkonfig

Function dokfs_postkonfig

Functions kre_revers_map, lit2mlid_kre_revers_map

To be done at startup in postkonfig.

    args := lit2kol, kol2lit
    lit2kol := string
    lit2kol => 'lit2mlid'
    kol2lit := string
    kol2lit => 'mlid2lit'
    rets := revers_map

The source map is found in $m->{cache}->{lit2kol} The target map is stored in $m->{cache}->{kol2lit}

Function postkonfig

Configuration Functions (overwritable)

Function html_filename

How html file names are formed when a stem and a two-letter language code are given.

The Apache configuration may have to contain the same configuration information if content negotiation is to be used effectively.

Function mlid_put_mltxt

Write a document- and language-specific tag and value to the database.

arg1 is the tag (mlid), arg2 the value (mltxt).

Function svnbasdirs2dir

Overwritable fallback function that specifies how dir2dir works in case the base directory is not specified in the svnbas2dir configuration option

    sig_oas, 08, 09  => /sig/oas/08/09 

General Functions

possibly belong to a lower layer

Function htmlesc

Escape text for use in html

Function tmpltag


    $p->tmpltag({ TAG_STYLE => 'star', POST_CHOMP => '-' }, 'SET', 'dummy', '=', 1);

        => [* SET dummy = 1 -*]

    $p->tmpltag('SET', 'dummy', '=', 2);

        => <% SET dummy = 2 %>

Arg 1 is an optional reference to a template options hash as described in Template::Manual::Config.

If arg 1 is not a reference, it is omitted and $m->{cache}->{tmplopts} is consulted instead.

Parse and write document metadata

Function url_parts

Take an URL, return a list consisting of protocol, domain and the file path (as a list of directory parts and a final filename)

Function set_url_parts

set the object field 'url_parts' to a reference to the list of values returned by url_parts

Function reldirs

subroutine of reldir and relurl

Function reldir

Function relurl

Take an url and, if possible, reduce it to its url as seen from the current document $m->{dok}.


    # $m->{dok} => 'a2e_css' , $m->dok2absurl($m->{dok}) = '' 
    # => ../perl/A2E/

Function lokurl

The whole file path of the url given as argument, from the perspective of the current $m->{url}, starting from the web server\'s top directory.

Function set_url

Find info about my own url, derive further info from it and store it in me.

Function init_navdoks

Collect and store some info that is needed for generating menus and other navigation help.

Make sure this is done only once.

Function set_alidoks

read alias info from database into memory.

Function littups_put_db

Write language-specific text variables into the langtxts table. These include the ones specified via 'special lit2mlid'. They no longger include language-specific extensions specified with tmpltoks because these are not document-specific and thus not written into table 'langtxts' but rather, after some more complicated mapping, 'flddes'.

    $m->littups_put_db({ tit => 'hello world', sut => 'i am greeting you', des => 'my first try', lab => 'hello' }, 'en', 'phm_salut081224'); 

The contents of the hashref mandatory first argument is written to the database.

Further optional arguments specify the language and the document.

Function putdoks

write subdocuments info into database

Subroutine sup_dok2dir

From a parent directory generate a hashref table that maps document names to directories

Function set_topdoks

Read from database which document nodes are root nodes (topdoks), and store this info in the object $m as follows.

Any document node $dok that has no other node above itself is marked with $m->{topdoks}->{$dok} = 1.

Return the number of topdoks thus found.

This should come near the beginning of most programs that use A2E::Dokfs.

Many other routines depend on the info being set. Unless given a true first argument ($force), it returns without reading the database anew (in the topdoks_already_set block) if it finds that the topdoks info is already there.

Another method of finding out whether a given dok directory is at the top of a microsite is provided by function topinddokp.

Function alidok

return the final document identifier to which a chain of aliases may be pointing.

Document identifier URL Scheme

In the good old days of txt2html, we used to write [dok:a2edb_perl_pub], like a kind of URL in analogy for [].

This is poorly documented and mostly unused now because we are relying on a more programmable formatter, deplate, which encourages different solutions.

Function relurltit_url2dokfol

dok: registered document identifier fol: leaf, file which is found in the directory

Function relurltit

Function ahref

Function ahref_item

Function hreftext

Used in generating menus

Function imgurltit

Function url2dok

Function x2urllab

These are needed by menu-generating programs such as nav2html and makedoksrow.

Function get_langtxt

Get a chunk of text, specifying the mlid (identifier, e.g. 'label') and optionally dok, lang and uid. Usually the latter three are preset.

Function lit2mlid

convert 'lab' to 'label' etc, using the user-specified lit2mlid hash

Function mlid2lit

convert 'label' to 'lab', etc using the reverse index of the user-specified lit2mlid hash

Function get_mltxt

Like get_langtxt, but first convert with lit2mlid so that 'lab', 'sut' etc can be used

Function get_langtxt_lab

Return the label, normally in the current language and of the current document, but optionally taking dok and lang as arguments.

Function get_langtxt_tit

Return the title, normally in the current language and of the current document, but optionally taking dok and lang as arguments.

Function get_langtxt_sut

Return the subtitle, normally in the current language and of the current document, but optionally taking dok and lang as arguments.

Function get_langtxt_des

Return the description, normally in the current language and of the current document, but optionally taking dok and lang as arguments.

Function dok2urllab

take document identifier (dok), return url and label

Function doklangs

Return sequence of preferred languages for linking, based on what the user indicated, what the current document uses and what the target document $dok allows.

Function relspe2rekmap

Based on a relation specifier such as


return a tree containing the info needed to construct sql-based put/get queries from vocabulary data.

In the a2e_perl_ebnf (a2e-perl-adapted Extended Backus Naur Form) notation, the input and ouput of this function can be explained as follows:

    args :: arguments
    args := relspe
    relspe :: relation specifier
    rets :: return values
    rets := rekmap
    rekmap :: database_record_info
    relsep => [ [ 'adr', 'person' ], [ 'postkod', 'plz' ], [ 'urb' ], [ 'urber', 'urb2' ], [ 'strad', 'str' ], [ 'strader', 'str2' ], [ 'dom' ], [ 'domer', 'dom2' ], [ 'adrrem', 'rem' ] ];
    relspe := listref(rekide, fldspe+)
    rekide :: record identifier
    rekide => [ 'adr', 'person' ]
    rekide := listref(tab, idekol+)
    fldspe :: field specifier
    fldspe => [ 'postkod', 'plz' ]
    fldspe := listref(kol, lit?)
    kol :: column name
    kol => 'postkod'     
    kol := symbol
    lit :: textchunk name
    lit => 'plz'
    lit := symbol
    tab :: table
    tab => 'adr'
    tab := symbol
    ikdekol :: name of identificatory column
    idekol => 'person'
    idekol := symbol
    symbol := string(symchar+)
    symchar := char(a-z,A-Z,0-9,_)
    rekmap => [ 'adr', [ 'person' ], [ 'urb', 'str', 'dom' ], { dom => 'sdom', person => 'user' } ]
    rekmap := listref(tab, idekols, atrkols, column_textchunk_map)
    idekols :: identifying columns 
    atrkols :: attributive columns
    atrkols => [ 'urb', 'str', 'dom' ]
    atrkols := listref(atrkol+) 
    atrkol :: attributive column
    atrkol => 'urb'
    atrkol := symbol
    kollits :: column_textchunk_map
    kollits => { dom => 'sdom', person => 'user' }
    kollits := hashref((kol, lit)+)

Function tmpl2dabalits

    args := tmpl, nonlit+
    nonlit :: excluded textchunk

return a listref with all the language variables (lits) corresponding to all the database relations that are tied to a given document type (tmpl). Arg2ff is a list of excluded lits.

Function rellits2putrek

Obtain full info that can be put into a record of the global database.

In the a2e_perl_ebnf (a2e-perl-adapted Extended Backus Naur Form) notation:

    args := relspe, littups
    relspe :: relation specifier
    relspe => [ [ 'traprop', 'dok', 'lang' ], 'prelang', [ 'tranom', 'lfol' ], [ 'trauid', 'user' ], [ 'tradat', 'hodie' ], [ 'travers', 'ver' ] ]
    relspe <= relspe2rekmap
    littups :: textchunks to be used as template variables, named as in vocabulary files and dbm hashfiles
    littups := hashref((litnom, litval)+)
    rets :: return values
    rets := putrek, idelits
    putrek :: info that can be passed to $m->put so as to put the record into the database
    putrek => [ 'traprop', { lang => 'de', dok => 'hrjaN3' }, 'trauid', 'nist', 'tradat', '2010-03-31' ]
    idelits => [ 'dok', 'lang' ]
    idelits :: identifier variables
    idelits := listref(litnom+) 
    putrek := listref(tab, ideflds, atrflds)
    idefls :: identifying_fields
    atrflds :: describing_fields
    ideflds := hashref((fldnom, fldval)+)
    atrflds := hashref((fldnom, fldval)+)

Uses relspe2rekmap to parse this data, as does rellits2getrek

Function rellits2getrek

Obtain full info that can be put into a record of the global database.

Input and parsing is like in rellits2putrek.

Output is like in rellits2putrek, but with a smaller first return value column names instead of column tuples and with a second return value.

Here is the synopsis in a2e_perl_ebnf:

    args := relspe, littups
    rets := getrek, kollits
    getrek :: arguments suitable for &A2E::Daba::get_record 
    littups := hashref((litnom, litval)+)
    kollits :: column-textchunk map
    getrek := tab, idetups, atrkols
    tab :: table
    idetup :: identificatory tuple
    atrkol ::  attributive column
    idetup :=  idekol, ideval
    idetups := hashref(idetup+)
    atrkols := listref(atrkol+)
    idekol :: id column name 
    ideval :: id column value
    getrek => [ 'traprop', { lang => 'de', dok => 'oas_akt1003' }, [ 'prelang', 'tranom', 'trauid', 'tradat', 'travers' ] ]
    kollits => { trauid => 'user', prelang => 'prelang', tranom => 'lfol', travers => 'ver', tradat => 'hodie' }

Function dok2relsdata

Retrieve the document's metadata from the rdb tables indicated with the special tmplrels directive.

    args := dok, data
    rets := data
    data := hashref((nom, val)+)
    data :: initial data tuples on their way to become complete littups

Do not retrieve anything from dbm files -- that is done on a higher level in &A2E::MLHT::dok2tmplvars.

Function get_dokdata_cache_rek

Return a pointer to a hash that contains cached document metadata, conventionally called $data and pointing to $m->{dokreks}->{$dok}->{$lang}, functioning as a handle for reading and writing.

If caching is turned off by means of the --dokdata_cache option, just return an empty hashref.

Function dok2data

Similar to dok2urllab, but return a hash of all the language-dependent metadata found in the database

    args := dok, lang
    rets := littups

Function db_dok2absurl

retrieve document's url from database.

subroutine of dok2absurl.

Function dok2absurl

Take dok, return absolute url (beginning with 'http://')

Use dir2url if referring to current document, otherwise search database.

Function dokurls

return both absolute and relative url for dok, where dok is a document symbol with an optionally appended relative pathname

Function dok2relurl

take dok, return url, as relative as possible, as short as possible (only directory, without full filename 'index*.html', if the rest can be handled by content negotiation)

Function dok2lokurl

take dok, return url, as relative as possible, as short as possible (only directory, without full filename 'index*.html', if the rest can be handled by content negotiation)

Function alidok_pur

simpler version of alidok.

possibly no longer needed.

Function supdoktyp

superior document (in the hierarchy) and pretyp (type of subordination relation, 2 for group member, 3 for subdirectory).

exit with error if our dok has no superior node and is also not among the topdoks.

Presupposes set_topdoks.

  arg1: dok.  if nothing given use $m->{dok} or get it from current directory

Function supdok

superior document (in the hierarchy).

Function supdir

Pathname of superior document node.

Optional first argument: current dok.

Optional second argument: minimal level of subordination, default is 3 = real directory subordination relation, 2 is a document group subordination relation, 1 a precedence relation among equal peers.

Function supdirdoktyp

like supdir, but also return the corresponding dok (document symbol) and pretyp (subordination type by which its first subdocument is linked to it, usually 2 = group member or 3 = directory).

Function doksfile

takes dok, returns name of file where current level\'s hierarchy info should be stored, e.g. '_subdoks' or '_grpdoks', depending on where in the hierarchy we are.

Function doksfiles

Function make_doksfile_line_rewriter

Create closure functions used by rewrite_doksfile.

Each function is an operation designated by a symbol. Currently we have 'mv' (move) and 'rm' (remove).

The function accepts a list of symbol_word_s that were found before the operation and returns a list of symbol_word_s that remain on that line after the operation (renaming or removing) is completed.

Function rewrite_doksfile

rewrite doksfile $1, applying procedure $2 with following arguments to each line found in the doksfile.

Supported procedures are

    mv $id0 $id2
    rm $id

That is the following invocations are supported:

    $m->rewrite_doksfile('akt/_grpdoks', 'mv', 'a2e_prog0710', 'a2e_adv0710');
    $m->rewrite_doksfile('_subdoks', 'rm', 'a2e_prog0710')

The first renames occurrences of a2e_prog0710 to a2e_adv0710, the second removes them.

The files consist of lines which either contain one or more blank separated document identifiers (dok) or comments starting with a hash mark (#). Comment lines are left untouched. Blank lines are removed. When a line contains an identifier that matches the searched one (i.e. arg1 of 'rm' or 'mv'), the identifier is rewritten (i.e. replaced or deleted) and everything else stays unchanged.


  FIXED: 2007-12-07: application the 'rm' had been leading to empty files.
  ? duplicated effort: similar code in get_doks, A2E::Subdoks::doksfile_add ?

Function url2dir

Derive local directory from corresponding URL.

Inversion of dir2url, core part of dokdir

Function rurl2lurl

Derive local url from remote url.

needed by A2E::Cgidok.

Function dokdir_pur

core part of dokdir: return local directory corresponding to a dok.

Function dokdir

Take dok url, e.g. something like oas0708/spez/, return pathname of corresponding directory on the local host. Suitable as an argument to chdir. An option lang argument should decide whether and for which language we want the dir/url localised. If a global $m->{lang} is set then that has the same effect. Localisation of dir/url names is done by using the alternative directory names stored in traprop.tranom.

Function dir2dir

take directory, typically the one returned by Cwd::getcwd, and convert this to what the name should ideally be when used in the local file system with shell commands like `cd', e.g.

    /homdisk/svn/sig_adv/perl/A2E --> /sig/perl/A2E

The second form is built on symlinks.

This requires configuration, see configurable section above.


FIXED: /ffiinnc/sig/08/05 --> /sig/ffiinnc/08/05

This should not happen. It leads to wrong urls generated by dir2url.

SOLUTION: in dokfs.konf: svnbas2dir sig_ffiinnc = /ffiinnc/sig

FIXED 2008-09-15: /eupat/papri/europarl0309/amends05 --> /amends/05

Wrong URLs generated when directories end in dates. SOLUTION: closure $matchdir, removed old function svnbas2dir

Function dir2fol

leaf of directory

        args := dir
        dir => /eupat/stidi/epla
        rets := fol    
        fol => epla

Very trivial provisional means of solving a problem in A2E::Dokdata without loading &File::Spec::Functions::splitdir there, a more robust way would be a function dok2fol that looks up dokprop.doknom

Function doklfols

Localising links to the leaf of the current document, e.g. 'papers', 'papiers' and 'papiere' for document 'swpatpapri' with leaf 'papri'.

Function dir2url

Derive URL from directory argument or current working directory.

Be fast, ignore @url files and database.

Function get_dok

find the document identifier (dok) of the current directory.

Use several methods, each of which are separately defined as a plugin: - search in a file @dok - search in the document names @dok-*.txt and @top-*.??.txt - search in the Makefile.

plugin constructor make_meta2dok

invoked by configuration statement

    get_dok_plugins = meta

plugin constructor make_makefile2dok

invoked by configuration statement

    get_dok_plugins = make

plugin constructor make_dir2dok

invoked by configuration statement

    get_dok_plugins = dir

implemented as a wrapper around function dirdok.

Function get_dok

get current document using plugged-in methods according to their sequence of priority

Function set_dok

invoke get_dok and write the result into $m->{dok}.

Function fayl_set_url

find url in url_fayl and write derived info to database.

Function dirlangs

Return languages of document, based on what is found in the languages file (normally '@langs') of the directory given in arg1 which defaults to the current directory. Analogous to dirdok.

Ideally the languages should be all in the 1st line and separated by whitespace, but this routine is a bit more tolerant. It also accepts comment lines and spread of languages across more lines. Moreover it eliminates doubles.

Function get_langs

find languages of the current directory or the directory belonging to the document identifier of argument 1.

Function set_langs

store the findings from get_langs in the object

Function valid_subdir

take subdir name and return same if it contains a valid subdocument node, otherwise return nil.

Function subdirs

Return the list of subdirectories which may need to be checked/parsed/compiled before the current directory is committed to the subersion repository.

These subdirectories must be in the same subversion repository.

Consequently they can not be symlinks.

Function set_subdirs

Set the object property 'subdirs' to the list returned by subdirs and return a string representation of that list where the subdirs are separated by whitespaces or, alternatively, by a separator specified in arg 1.

Some programs such as dokfs_subdirs may depend on the returned string, but in the long run this should be in a separate function, not set_subdirs. Normally the subdirs function should be used, and set_subdirs should onyl be used as a shorthand for setting the subdirs property.

Function get_doks

find the documents of the current document hierarchy level, as typically stored in a _subdoks or _grpdoks file and in corresponding database records.

Subroutine fayl_postdoks

Return documents of current hierarchy level from a file

Subroutine dirs_subdoks

Reconstruct documents of current hierarchy level from what is seen in subdirectories and return them

TODO extend to deal with _grpdoks subordination of pretyp 2 as well, use /adv/prg/bin/ as a model and possibly as a common basis

Function set_doks

store the findings of get_doks

Function rewrite_subdoks

Find all subdoks of the current node and append them to the right _subdoks file as far as they are not already found there or in an inferior _grpdoks file.

Functions doksrc, unidoksrc, muldoksrc

Take document identifier (dok), return full path of the editable source file, either multilingual or in specified language or in document's primary language.

Function unidoksrc

Function muldoksrc

Function doksrc

Document Hierarchy

This is a basis not only for generating menus but also for determining which templates, css files etc to use in generating the object files.

Function get_predoks

    args := dok, (nom=> val)*
    rets := predoks*

list the whole chain of superordinated dokuments from the topdok level down to the given dok, using memory if possible, file system or database otherwise.

Option topinddok defaults to 'topdok' but could also be set to 'inddok'; in the latter case the hierarchy ladder is climbed up to the web domain root directory (where a sitemap_index is to be created) rather than to the microsite (topdok) root (where a sitemap is to be created). Option NFaylP means dont read from filesystem, DabaP means read from database.

Once predoks were obtained properly they are stored in m->{${dok}_${topinddok}_predoks}.

Function set_topdok

Find upmost node of site, set predoks hierarchy on the way.

Stop unless information about topdoks ($m->{topdoks}) has been collected, e.g. by set_topdoks.

Function set_topdir

find and store the topdir, i.e. the directory corresponding to the topdok.

This is info needed by the Makefiles that generate object files using templates and CSS files that are stored in this directory.

Function topdir_svn_cleanup

perform cleanup at topdir level, thus avoiding locking bugs that tend to occur when it is done at a lower level.

Function set_topcss

Set the filepath of the CSS file as referenced in the HTML object version of the dok.

Return non-null if successful;

Function fayl_predoks

Take dok argument, read the whole chain of superordinated documents from the file system

Subroutine supdir_set_dokprop

Read document tree from parent directory, return a hash that contains all possibly needed information and is built like $m->{dokprop}

Function daba_predoks

Take dok argument, read the whole chain of superordinated documents from the database.

Function daba_postdoks

Take dok argument, read from the database the chain of subordinated documents as far as they belong into a menu.

Generation of Menus

Used by nav2html(1), makedoksrow(1)

Function menu_subdoks

Take a dok, return the flat list of direct subordinates of this dok, as far as it has subordinates (not just postdoks!).

Function subdokmenu_entry

Take a dok, return its entry for the left-hand navigation menu of the HTML version.

Function subdokmenu_entries

Format the menu_subdoks for an HTML menu.

Function listitem

Format an item for a list used in an HTML menu.

Higher level applications can tweak this by setting the $m->{lifmt} variable.

Function subdokmenu

Format the whole subordinate menu of the current document and return it.

Function dokmenu_entry

take a dok, navdok and subdokmenu, return the dok\'s menu entry.

navdok is the document for which the menu is to be created, subdokmenu is the pre-formatted menu that is only used if we happen to be formatting the entry for navdok itself.

Function predoks

The chain of superordinate documents that belong into the menu, starting from the top, ending at the document given in arg1 or my current dok.

This chain is a bit thinner than the full chain. As we move up the directory hierarchy, only those nodes from which sub-ierarchies are forked out remain important.

We distinguish between level 3 and level 2 sub-hierarchies (subdoks and grpdoks). When moving up the hierarchy, level 2 becomes irrelevant as soon as we have reached a level 3 fork.

At the document itself we are at level 1 (sequenced leaves of same node). We list the preceding leaves, before that the superordinate groups, before that the superordinate directories.

We can set the initial level as an option

    typ_min => 1

in arg2ff, which is a hash of options.

Function postdoks

Posterior documents of the current hierarchy level, as far as they ought to appear in a menu.

Function menudoks

All documents of the menu's current level

Obsolete, needed for backward compatibility with old menu generation mode.

Function dokmenu_entries_sub

This does most of the work of dokumenu_entries and allows more fine-tuning than dokmenu_entries itself.

The extra choices are needed by some applications such as makedoksrow.

Obsolete, needed for backward compatibility with old menu generation mode.

Function dokmenu_entries

take a dok, return a full HTML menu for navigation, as typically used on the left side of a webpage.

Obsolete, needed for backward compatibility with old menu generation mode.

Support for various dokfs operations (set alias, delete)

Function set_alias

set an alias, e.g. from the commandline, and store it in the database.

Function rmtalias

delete an alias from the database.

Invokable from the commandline with rmtalias(1)

Function rmdok

Erase a given document and all related info from the database (DBDEL) and from the doksfile (subdoks, grpdoks). PREPOST: Leave no hole in the document chain, connect the preceding to the following. SUBDOK: Refuse to erase a document that has subdocuments.

Function deldok

Strip document of its topdok status and remove any template files that testified this status.

Function set_pwd

set present working directory $m->{pwd} with ideal path name or whatever is given to it.

Function dirdok

return the dok (document identifier) found in the given dir (directory).

Function rmtdirsub

take fol (directory leaf) argument, erase the document found at dir from the file system and the database. %arg2ff are options, including

    force: move ahead recklessly

This is normally invoked only via a recursive version rmtdir which also removes subdirectories.

Function rmtdir

Recursively remove a document along with its subdocuments. Invocable from commandline as

    rmtdir <name>

Functions url_fayl, dok_fayl, nav_fayl, dok_lng_faylz, lng_tmpl_faylz

TODO: These must be connected to the configurable file name templates unifnom, mulfnom, lngfnom etc



Function dok_fayl

Function nav_fayl

Function lng_fayl

Function antefayl

@pre.$dok.$lang.txt or, when $lang is null, @pre.$dok.txt

Function dir_srclang

get first language of current document if there is one

Function dok_pre_lng_faylz

All vocuabulary files belonging to one document, language-neutral before language-specific, template-specific before document-specific.

The first position must be occupied by a prependable file and, if no such file is available, by an empty string.

rank_sufiks is the rank suffix '?+', '' or '?-' that specifies which variable assignments (for unimportant nodes: exported assignements only, for normal nodes: all assigments except unexported ones, for important nodes: all assignements including unexported ones) should be read from the concerned file. For the appended vocabulary files, only those of the current node $m->{dok} are important (of high importance), the other ones are unimportant (of low importance). Template files and prepended (antefnom) files are of normal importance.

It is recognised in A2E::Tmplfil(3) by riid_tmplvars_fayl and used there by tmplini, where more explanations are found.

Function unshift_suptmpls

recursively add superior template directories to head of directory list. also add $m->{tmplang} subdirectories of these, e.g. /opt/a2e/share/tmpl/mlht/a2e/sig_aammdd/multemp subroutine of lng_tmpl_faylz

Function lng_tmpl_faylz

template files with which LNG_FAYLZ starts

Function top_fayl

Function lng_faylz

arg1: lang
arg2: dok
rest: options

list only files that exist and are readable


list pairs: one language-neutral, one for lang

if not true, list language-dependent files only


Normally, where possible, the source language version is read so as to provide defaults in case no lit is there in the current language.

Set nosrclang true to switch off this behaviour.


Function set_dok_langs

used by

Function dok_kre_kanal

Create channel: set up the current document as a news channel. Argument 1 is the name of the channel to be created. If this is '1', $m->{dok} is used. If it is '0' or empty, nothing is created. The name of the channel is usually derived from the news_kanal configuration option, but some cases, as in A2E::Mktdir, it is obtained from elsewhere. The other elements of a channel record, which correspond to the news_kanalrem, news_kanaldat and news_supkanal configuration variables, can also be supplied as commandline arguments. The

Function dok_put_kanals

Insert the current file into one or more news/rss channels. This routine is used by mktdir and dokdata2db.

Function ml_dok2absurl

like dokurls but using predoks info to climb up the tree so as to find a more up-to-date or multilingual URL

Function set_sems_tmplvars

New functions, to be classified



Hey! The above document had some coding errors, which are explained below:

Around line 61:

=over should be: '=over' or '=over positive_number'

Around line 652:

Non-ASCII character seen before =encoding in '碳化物'. Assuming UTF-8

Around line 661:

You forgot a '=back' before '=head2'

Around line 682:

'=item' outside of any '=over'

Around line 690:

You forgot a '=back' before '=head1'

Around line 3370:

Unknown directive: =head

Around line 4370:

=pod directives shouldn't be over one line long! Ignoring all 4 lines of content

Around line 4419:

Unknown directive: =head