2024-09-24 | Maven 3.9.9 |
2024-08-13 | Noble Numbat |
2024-06-21 | Maven 3.9.8 |
2024-02-02 | Maven 3.9.6 |
2023-10-11 | P2 repository deleted |
2023-10-10 | Maven 3.9.5 |
This documentation is extracted from the pod/man manuals. Please refer to these documents for more details.
Preamble
The ArakhnĂȘ Web Generator, aka. AWebGen, is a offline website generator. This generator is replacing internal macro commands in a set of files to generate the HTML website.
Synopsis
awebgen [options]
Command-Line Options
- --[no]announce
Send announcement email.
- --[no]autoscript
Generate or not the PHP scripts predefined in AWebGen.
- -f
If mirroring is enabled, force AWebGen to upload all the file and not only the changed files.
- --maintenance
Set the maintenance flag on. Depending on your website style, it could change the look of the generated site.
- --mirror=url
Put the generated website on the remote host.
- --nomirror
Avoid to put the generated website on a remote host.
- --password=text
Specify the password to use to be connected to the mirror host.
- --rss=filename
Generate a RSS file, and change its name to "filename.rss". A RSS file named "news" is generated by default.
- --norss
Do not generate a RSS file.
- --style=name
Copy the files of the style with the given name into the current site. The previously installed style is deleted. When this option is used, AWebGen does notging else.
- --stylelist
Display the list of the style templates that are provided by AWebGen.
- --test
Generate a test website in the directory
../test/
.- -v
Be verbose.
- --version
Display the AWebGen version and copyright text.
Configuration Directory and Files
The configuration directory, here labelled by "config_path
" is supposed to be located in the root directory of the website to generate. By default, the "config_path
" is "./.awebgen
".
The configuration file is a XML file named "config_path/config
".
The configuration file must contains the tag <AWEBGEN />
. The following subsections describe the inner tags.
a. Profile Definition
Profiles could be defined according to several contraints. A profile could restrict the configuration entries.
A profile must be defined in the tag <PROFILES/>. The following example defines a default profil named "home" and a profile named "work" which is enabled only if the host IP matches the given network addresses.
<PROFILES>
<PROFILE name="home" default="yes" />
<PROFILE name="work">
<NETWORK ip="10.85.0.99/24" />
</PROFILE>
</PROFILES>
b. Constant Definition
Is is possible to define a set of constant values in AWebGen. These definitions must appear in the <CONSTANTS/>
tag. Each constant pair is defined in a <CONSTANT>
tag as followed:
<CONSTANT id="constant_name" value="constant_value" profile="profile_name" />
where the constant_name
must be unique. If the profile was given, the constant will be defined only if the corresponding profile was enable. If no profile was given, the constant is always defined.Several constants are recognized and used by AWebGen:
announce-format
indicates if the annoucement emails should use a HTML or a text form. Value must be one of "html" or "text";COPYRIGHT_STRING
is copyright string "© y1-y2 n". y1 is corresponding toCOPYRIGHT_FIRST_YEAR
, y2 toYEAR
constant, and name toSITE_NAME
constant;CSS_FILE
is the URL of the CSS file;DIFFERED_GENERATOR
is an HTML string which is containing the name and the version of AWebGen. This variable will be replaced in the HTML files during the mirroring stage only;EMAIL_CRYPT_KEY
is the string which may replace the "at" character (@) when crypting email addresses.GENERATOR
is an HTML string which is containing the name and the version of AWebGen. This variable is immediatly replaced in the HTML files;GENERATE_SEND_MESSAGE_SCRIPT
is a string containing a boolean value ("true" or "false"). This constant indicates if the sendmessage PHP script will be generated. This constant is automatically set to "true" whenCONTACT_FORM
is expanded;HIDE_ML_FORM
is a boolean value which is used to indicates if the mailing list forms should be displayed or not;HOMES
is the directory where the user's home pages are located (by default "${ROOT}/homes");IMG
is the directory where images are stored (by default "${ROOT}/images");LAST_CHANGE_DATE
is the date of the last change of the page. This variable will be replaced in the HTML files during the mirroring stage only;PAGE_TITLE
is the title of the current page;PAGE_COMMENT
is the comment associated to the current page;PAGE_KEYWORDS
are the keywords associated to the current page;ROOT
is the relative path to the root directory;SMTP_SERVER
is the IP or the name of the SMTP server used to send announcement emails;SMTP_SENDER
is the email which will be used to send annoucement emails;SITE_IMG
is the path to the site's title picture (by default:../images/header.png
);SITE_NAME
is the name of the website;SITE_URL
is the URL of the website;TODAY
is the current date and hour in international format;YEAR
is the current year in 4 digits.
c. Page Definitions
It is possible to define several informations about the website pages in the <PAGES/>
tag. Each page is describes by a individual <PAGE/>
tag. The supported attributes of the <PAGE/>
tag are:
id
is the unique identifier of the page.url
is the path to the HTML page.label
is the full name of the page.short
is the short name of the page.parent
is the identifier of the page which is a parent of this page.snap
is the identifier used by the snap.php script to identify the files to download for this page. If the given string starts with "str|", the given str will be used in place of the first letter of the project name to build the download URL.push
is a list of coma-separated identifier of arrays in which the page identifier will be pushed.misc
is a list of coma-separated data associated to the page.profile
indicates the profile for which the page information are defined.
Example:
<PAGE id = "eclipse-subclipse"
url = "${ROOT}/eclipse/subclipse/index.html"
label = "Subclipse: a SVN plugin for Eclipse"
short = "Eclipse Subclipse"
push = "othersofts"
misc = "eclipse-subclipse" />
d. Ignore Definitions
It is possible to say to AWebGen to ignore several things in the <IGNORES/>
tag.
The tag <EXPAND pattern="<pattern>" profile="<profile>" />
permits to avoid AWebGen variable expansions in the file with a name matching the given <pattern>
(written as a shell wildcard).
The tag <MIRROR pattern="<pattern>" profile="<profile>" />
permits to avoid AWebGen to upload the files witha name matching the given <pattern>
(written as a shell wildcard).
e. Mirror Definition
Mirror hosts are used to upload the generated website. It is possible to define a mirror inside the configuration file with:
<MIRROR url="<url>" password="<password>" />
Currently, only FTP connexion are supported by AWebGen.
f. Annoucement Definition
Each time a news is appearing on the website, it could be also sent by email. To enable this feature, it is necessary to define a <ANNOUNCE/>
tag in the configuration file:
<ANNOUNCE email="<annoucement_email>" format="html|text" />
g. Array Definitions
It is possible to define arrays for AWebGen. Some of them are already known by AWebGen, the other could be directly used in your website skeleton files. Arrays must be defined as following (here each value are pushed at the end of the referenced array):
<ARRAYS> <ARRAY name="..." profile="..."> value </ARRAY> <ARRAYS name="..."> value </ARRAYS> </ARRAYS>
h. Hash Definitions
It is possible to define hash tables for AWebGen. Some of them are already known by AWebGen, the other could be directly used in your website skeleton files. Hashtables must be defined as following:
<HASHS>
<HASH name="..." profile="...">
<PAIR key="...">...</PAIR>
<PAIR key="...">...</PAIR>
</HASH>
<HASH name="...">
<PAIR key="...">...</PAIR>
<PAIR key="...">...</PAIR>
</HASH>
</HASHS>
HTML and Model Files
AWebGen uses existing HTML files from the current directory as the files to generate. Theses files could include a model file which must be located in the directory
"${ROOT}/.awebgen/include
". These files are complete or part of HTML files.
For each file (.html, .php, .asp...) AWebGen parses them and replaces macro commands by the associated values. The supported macro commands are:
- ${BEGIN:shtml_name}
is opening a local context and is expanded to the content of the style file named "sshtml_name.shtml" inside the style file directory. See ${END} to close the context, and ${INCLUDE} to include a complete style file.
- ${CONTACT_FORM:email}
${CONTACT_FORM:email:sender:subject:message}
${CONTACT_FORM:email:sender:subject:message:redirect_url}
${CONTACT_FORM:email:sender:subject:message:redirect_url:htmlcode} is expanded to a HTML contact formular. This formular is invoking the sendmessage PHP script. email is the address to contact. sender is the default email or name of the message's emitter. subject and message are respectively the subject and the content of the message to put by default in the formular. redirect_url is the URL of the page to be redirected to after the email was sent (by default the current page). htmlcode is a peace if HTML code put back at the end of the HTML formular.
- ${DEF:name=value}
defines a constant name with the given value. This macro is expanded to an empty string.
- ${DEFMACRO:name($param1,$param2...)=code}
defines a macro with the given name and the given parameters. The new macro will be expanded to code. Each name of parameter must be prefixed by a dollar sign. There parameter names (dollar included) may appear in the given code. In this case they will be expanded with the text passed to the new macro when it is expanded.
- ${DEFUSE:name=value}
defines a constant name with the given value. This macro is expanded to the value.
- ${DIFFERED:id:text}
markes the given text as "does not change the informational content of the page". The given text is expanded but temporary discarted to prevent any change of the last change date.
- ${EMAIL:email:label}
is expanded as a formatted email address link, optionally labeled with the given label.
- ${EMAIL_CRYPT:email}
is expanded to the crypted form of the given email.
- ${EMAIL_DECRYPT:crypted_email:label}
is expanded to the uncrypted form of the given email.
- ${END:shtml_name}
is closing a local context and is expanded to the content of the style file named "eshtml_name.shtml" inside the style file directory. See ${BEGIN} to open the context, and ${INCLUDE} to include a complete style file.
- ${FAILURE:text}
causes AWebGen to stop on a failure.
- ${FIELD:fieldname}
${FIELD:fieldname|default_text} is expanded to the value of the database field named fieldname if the field was defined, otherwise it is replaced by "" or default_text. This macro command is available only inside a database instruction such as ${FOREACH}.
- ${FOREACH:DB(dbname):text}
${FOREACH:DB(dbname)[min..max]:text} is expanding the text in which the fields extracted from the database named dbname are accessible with the macro command ${FIELD}. If the min and the max arguments are specified, only the database entries with an index inside the given interval will be treated. The macro constant ${LOOPINDEX} is localy defined and contains the index of the current field.
- ${FOREACH:HTML(style_id):dbase_content}
${FOREACH:HTML(style_id)[min..max]:dbase_content} is expanding the content of the style file named style_id on each entry of the dbase_content. If the min and the max arguments are specified, only the database entries with an index inside the given interval will be treated. The macro constant ${LOOPINDEX} is localy defined and contains the index of the current field.
- ${FOREACH:PAGE(part_id):text}
${FOREACH:PAGE(part_id)[min..max]:text} is expanded information on HTML pages into the text. The part_id specifies which is the information to be treated. It must be one of "url", "short", "label", "misc", "parent", "snap" for respectively the URL, the short name, the full name and the miscellaneous informations of the page (see "configuration file" section for details). If the min and the max arguments are specified, only the pages with an index inside the given interval will be treated. The macro constant ${LOOPINDEX} is localy defined and contains the index of the current field. The macro command ${LOOPKEY} is the identifier of the current page. And the macro command ${LOOPVAL} is the extracted value for the current page.
- ${FOREACH:SORTED(@array_id):text}
${FOREACH:SORTED(@array_id)[condition]:text} is expanding the text in which the macro commands $$ and ${LOOPELT} will be expanded to the value of the current array element extracted from an array named array_id. The array elements are sorted according to the given condition (Perl operators are used here) or by lexicographical order if not given.
- ${FOREACH:SORTED(%hash_id):text}
${FOREACH:SORTED(%hash_id)[condition]:text} is expanding the text in which the macro commands $$, $1$ and ${LOOPKEY} will be expanded to the key of the current hash pair extracted from a hash table named hash_id. The macro commands $2$ and ${LOOPVAL} will be expanded to the current pair value. The pairs are sorted according to there keys and to the given condition (Perl operators are used here) or by lexicographical order if not given.
- ${FOREACH:SORTED(id):text}
${FOREACH:SORTED(id)[condition]:text} is expanded to array values (see ${FOREACH:SORTED(@)}) or to hash values (see ${FOREACH:SORTED(%)}).
- ${GET:@array_id[index]}
${GET:%hash_id[key]} is expanded to the value extracted from an array or from an hash table. The first version is to extract the value at the specified index from the array named array_id (see configuration file section to define an array). The second version is to extract the value associated to the specified key from the hash table named hash_id (see configuration file section to define a hash table).
- ${IF:condition:then_text}
${IF:condition:then_text:else_text} is expanded to then_text if the condition is true (Perl operators are allowed), otherwise it is replaced by "" or else_text.
- ${IFDB:dbname:then_text}
${IFDB:dbname:then_text:else_text} is expanded to then_text if the database file named dbname is readable, otherwise it is replaced by "" or else_text.
- ${IFDEF:constantname:then_text}
${IFDEF:constantname:then_text:else_text} is expanded to then_text if a constant named by constantName was defined, otherwise it is replaced by "" or else_text. This macro does not checks the value of the constant, only its definition is taken into account.
- ${IFFIELD:fieldname:then_text}
${IFFIELD:fieldname:then_text:else_text} is expanded to then_text if the field was defined, otherwise it is replaced by "" or else_text. This macro command is available only inside a database instruction such as ${FOREACH}.
- ${IFMAINTENANCE:then_text}
${IFMAINTENANCE:then_text:else_text} is expanded to then_text if AWebGen was launched with "--maintenance" parameter, otherwise it is expanded to "" or to else_text.
- ${INCLUDE:shtml_name}
is expanded to the content of the style file named "shtml_name.shtml" inside the style file directory. See ${BEGIN} and ${CLOSE} to open and close a context.
- ${INCLUDEDEFS:local_file}
is a particular implementation of an inclusion macro. It read the given local file (relative filename from the directory where the file of this macro is located) and ignore all the things (macros, HTML text) inside except for the definition and condition macros (DEF, IF...).
- ${JAVASCRIPT:javacode}
permits to protect a peace of Javascript source code. This macro encloses th given Javascript code inside the standard tags
<script type="text/javascript">
and</script>
.- ${LENGTH:array_id}
is expanded by the size of the array with the specified id.
- ${LINK:url}
${LINK:url:label} is expanded to an HTML <a> tag with the given url and optionnally the given label.
- ${LOGENTRY:soft_id:version:authors:date:log_text}
is expanded to the default log entry.
- ${PAGE:page_id}
is expanded by the url of the HTML page with the given page_id. See the configuration file section to define the pages.
- ${PAGELABEL:page_id}
is expanded by the full name of the HTML page with the given page_id. See the configuration file section to define the pages.
- ${PAGELINK:page_id}
is expanded by the full HTML link (with url and <a> tag) of the HTML page with the given page_id. The label of the link is the long description of the page. See the configuration file section to define the pages.
- ${PAGEPARENT:page_id}
is expanded by the identifier of the parent of the page.
- ${PAGESHORTLABEL:page_id}
is expanded by the short name of the HTML page with the given page_id. See the configuration file section to define the pages.
- ${PAGESHORTLINK:page_id}
is expanded by the full HTML link (with url and <a> tag) of the HTML page with the given page_id. The label of the link is the short description of the page. See the configuration file section to define the pages.
- ${PROVIDE:text=value}
defines a constant name with the given value if it was never defined before. This macro is expanded to an empty string.
- ${PROVIDEUSE:text=value}
defines a constant name with the given value if it was never defined before. This macro is expanded to the value of the constant.
- ${REMOVETAGS:text}
is expanded to the given text in which all the HTML tags were removed.
- ${REPLACE:text_to_replace:replacement_text:text}
is expanded to the given text in which all the occurences of the text_to_replace are replaced by the replacement_text. This function does not support regular expressions as text_to_replace.
- ${STR:text}
ensures that the given text is a valid Perl text (protect the quotes...).
- ${STYLIZE:text}
is expanded to the given text in which the current style may change some things. This macro permits to apply several style's classes on the HTML tags according to the current generation style. By default this macro does nothing.
- ${TEXTLIST:text}
${TEXTLIST:text:uclass:lclass} assumes that the given I
is written according to a textual-list syntax (see below). This macro expands the textual-list to its HTML equivalent. In textual-list syntax, the list has two hierarchical levels. Each line starting with a star (*) character is assuming to be a list's entry in the upper level. Each line starting with a indent (-) character is assuming to be a list's entry in the lower level. When given the I and I correspond to the CSS class styles of the UL tags for the upper and lower levels respectively. Example:
* First top level * Second top level - First lower level * Third top level - Second lower level
- ${UNDEF:constant_id}
remove the definition of the given constant identifier.
- ${URLDECODE:encoded_url}
is expanded to the url representing by the given uuencoded url.
- ${URLENCODE:url}
is expanded to an uuencoded url.
- ${VALUE:constant_id}
${VALUE:constant_id:default_text} is expanded to the value of the constant named constant_id or the given default_text if the constant was never defined.
- ${WHILE:condition}
${WHILE:condition:code} is expanded to the given code until the condition is false. The condition may respect the Perl syntax.
Several HTML entities are directly expanded by AWebGen because they do not correspond to standard HTML but are provided by AWebGen for convenience because they have a specified semantic for AWebGen:
- "
&obrace;
" is expanded to "{
"; - "
&cbrace;
" is expanded to "}
"; - "
&obracket;
" is expanded to "[
"; - "
&cbracket;
" is expanded to "]
"; - "
&oparent;
" is expanded to "(
"; - "
&cparent;
" is expanded to ")
"; - "
$
" is expanded to "$
"; - "
☆
" is expanded to "*
"; - "
&col;
" is expanded to ":
"; - "
&column;
" is expanded to ":
". - "
&shtmlcomment;
" is expanded to "<!--
". - "
&ehtmlcomment;
" is expanded to "-->
".
Database Files
Database File Format
Several files are assumed to be databases in which a lot of data could be put and used by AWebGen. A database file is a text file in which each database entry is separated by a line with only the character ".
" on it. Each database entry is composed of fields. A field is defined by a field name and a value according to the syntax: NAME=VALUE
. The VALUE
could be written on several lines.
The dabase file are supposed to be in the directory "config_path/db
".
Standard Databases
Several standard database files are directly supported by AWebGen.
news.txt
contains the news of the website. The supported fields are "DATE
", "TITLE
", "TEXT
" and "LINK
" (optional). The name of the news database is given by the constantNEWS_DB
(by default "news
").
Autoscripts
A set of PHP scripts are embedded inside the AWebGen distribution. They could be directly put in the root directory of the generated website.
- index.php
A file
index.php
which is redirecting to the root page is generated in each directory without index file.- ml.php
The file
ml.php
permits to manage several mailing lists in a user point of view. This is generated only of a entry named "mailinglists
" was defined in the configuration hash tables (see configuration file section). This hash table should map the mailing list identifiers as keys and the mailing list addresses as values. Additionally, an hash table named "mailinglist-comments
" could be defined to map the mailing list identifiers to the textual descriptions of the mailing lists.To work properly, two constants must be defined:
ML_ADDRESS
andML_REQUEST_ADDRESS
. Both are email address pattern in which the string "${NAME}
" will be replaced by the identifier of the mailing list. TheML_ADDRESS
constant represents the posting email address to the mailing list, and theML_REQUEST_ADDRESS
represents the register/unregister email address to the mailing list.The
ml.php
script displayes a page on which it is possible to register/unregister an email to/from a mailing. The "fullpage.shtml
" file style is assumed to provide the HTML page skeleton.- redirect.php
The file
redirect.php
is generating at the website root. It permits to display a redirection message to a given url (specified with the HTML GET parameter named "url
"). The displayed page is based on the model file "fullpage.shtml
" (see model files section).- sendmessage.php
The file
sendmessage.php
> permits to send emails. It is generated only when the constantGENERATE_SEND_MESSAGE_SCRIPT
is set to "true". This script provides a contact formular with a security image to prevent robots to send emails.The
sendmessage.php
> script displayes a page on which it is possible to fill the contact formular. The "fullpage.shtml" file style is assumed to provide the HTML page skeleton.- snap.php
The file
snap.php
permits to be redirected to a download page of software snapshots. It takes as several GET parameters:- the "
project
" name and optionally the "subproject
" name. The snapshot URL is assumed to be defined inSNAP_URL
andSNAP_URL_SUBPROJECT
depending if the subproject name was given; - the Maven "
groupId
" and Maven "artifactId
". The snapshot URL is supposed to be given by theMAVEN_REPOSITY
constant followed by the group identifier and the artifact identifier. If the GET parameter "version
" is specified, the string "version-SNAPSHOT
" will be merge to the target location; In case the PHP script is requiring to explore the Maven repository, you must fill the constantMAVEN_REPOSITORY_DIR
with the local path to the Maven repository root; - the "
dir
" name of the project and the "subproject
" name. The snapshot URL is assumed to be defined by "flet/dir/subproject
" or by "flet/dir
" where "flet
" is the first letter of the "dir
".
The constant
SNAP_URL
must be defined as the redirection url when only a project name is given. The constantSNAP_URL_SUBPROJECT
must be defined as the redirection url when both a project and subproject names are given. If theSNAP_URL_SUBPROJECT
is not defined, it is assumed to be the same asSNAP_URL
. The macro commands "${FLET}
", "${NAME}
" and "${SUBNAME}
" could appear in the URL ("${SUBNAME}
" only forSNAP_URL_SUBPROJECT
). They will be replaced by the first letter of the project name, the project and the subproject name respectively.- the "
- spip.php
The file
spip.php
permits compatibility with a previous version of the website written with the SPIP content management system. Thespip.php
file is generated only if a database file named "spip.txt
" was defined (see database files section). The database file supports the following entries:- if
PAGE_ID
is defined it means that the entry if a standard page redirection. The spip page identifier must be put inPAGE_ID
field, the target url must be put inTARGET
field and optionally theCOMMENT
field could be defined; - if
AUTHOR_ID
is defined it means that the entry if an author page redirection. The spip author identifier must be put inAUTHOR_ID
field, the target url must be put inTARGET
field and optionally theCOMMENT
field could be defined; - if
ERROR_PAGE
is defined it means that the entry extends the message displayed my the "spip.php
" page in case of error.
If the file was generated other files that are correspondiong to oldest SPIP version are also generated:
article.php
,article.php3
,rubrique.php
,rubrique.php3
,auteur.php
, andauteur.php3
.- if
- websvn.php
The file websvn.php permits to be redirected to a WebSVN page. It takes as GET parameter the "
project
" name and the "subproject
" name. The redirection URL is specified in theWEBSVN_URL
andWEBSVN_FULL_URL
constants in the configuration files (see configuration file section). Each of these constants could contain the strings "${PROJECT}
" or "${SUBPROJECT}
" which will be replaced by the name of the project and the subproject respectively. TheWEBSVN_URL
is assumed to be the URL to access to the SVN with a project name only, and theWEBSVN_FULL_URL
is assumed to be the URL to access to the SVN with both project and a subproject names.