NOTE: MATERRA should be installed in a root directory of a domain or a subdomain, otherwise it will be necessary to manually modify file references (links) in js files.
Copy the contents of the public_html folder to your website root directory (generally public_html),
if you plan to allow user registration, copy [the empty] materra_db folder to the same directory holding the public_html folder (or update users/users.settings.inc.phpDB_USERS constant with a path where you want users database to be stored),
run setup.php (eg. by visiting https://yourwebsite.org/setup.php where yourwebsite.org should be replaced with your domain or subdomain name).
Optional (changing settings):
Changing settings (for cache, etc.) is done by editing files ending with settings.inc.php (eg. check.settings.inc.php).
Each such file affects only specific function or area of the website (eg. check.settings.inc.php provides settings for check.php which is used to check for updates,
one can open .php files in a text editor to see what they are used for).
One may also want to edit files ending with header.inc.php, as these contain webpage headers.
Note that, even if enabled, user registration will not be possible before the admin account is registered. Admin id (username) must be specified in users/users.settings.inc.php, by updating
the ADMIN_ID constant. Afterwards, you can use ID command in MATERRA to change your id to specified admin id and then REG command to register the account.
Chapter Usage updated.Usage
Usage of MATERRA is simple.
Type "?" or "help" (without quotes) in the command line interface (CLI) for a list of commands and additional help on usage.
While MATERRA supports creation, editing and upload of webpages through the web interface, prior to upload, content is stored in local browser storage which may not be reliable.
Thus, for any serious work it is recommended to use a text editor (eg. Notepad++) to create and edit webpages.
UPDATE: As of version 2021.10.24, MATERRA includes a text/html editor which has support for
MATERRA tags and makes writing and upload of webpages much easier.
Creation of webpages in a text editor
Apart from the main page (/index.html), webpages in MATERRA do not have to have a html header/footer. However, this is recommended as it will enable direct access to the webpage.
This header should look like this:
Click here to show the header code +
Here, WEBPAGE_TITLE should be replaced with the actual title of a webpage.
If html header is added, the html footer should be added too:
Click here to show the footer code +
The article should then be written in between (between the starting (<body>) and closing (</body>) body tag).
It is not required, but it is also recommended to define author name, keywords and other details using specific tags, like this:
Click here to show the code +
Use log_id tag only if you want MATERRA to generate a page header showing article creation date, date of last update and author name. The content of the tag (in this case '22') is
irrelevant and can be left empty.
Here is a list of tags that may be used here:
tag
description
additional notes
log_date
date of article creation
log_update
date of last update
by default, this is filled automatically and should be left empty
log_mtime
file modification date
by default, this is filled automatically and should be left empty
log_author
author name
can contain additional tags - log_address and log_email, specifying affiliation or address and email, this data is used in LaTeX generation. In case of multiple authors, use one log_author tag for each author.
log_desc
short description of the work
useful if writing a log type webpage, this will then be used in log index page
log_category
category
useful for log type webpages, used in log index if categories are enabled
log_tags
keywords
used in log index and LaTeX generation (as keywords)
log_keywords
words to highlight
case sensitive, these phrases will be highlighted (bold) in the article
log_cls
document class, eg. article
used in LaTeX generation
cite_year
year of publication
used for citations, by default, year will be extracted from log_update or log_date, so it is unnecessary to specify this if log_date is specified
cite_doi
alternative link to article
used for citations
cite_contrib
an address for contributions
this can be a wallet or web (URL) address for support
pdf_link
link to a pdf version of the webpage
available from 2022.02.26, if present, an pdf icon linking to pdf will be shown in page header
set_body_numbering
controls auto-numbering of chapters
set to 0 to turn off automatic numbering
ref_authors
alternative generation of citations/references in LaTeX
sorts LaTeX references by author's last name, changes in text citation to include last name and publication year instead of numbering (automatically adding alphabetic suffix to years in case of multiple references with the same author/year (e.g. Einstein, 1905a and Einstein, 1905b)
latex_package
package to use in LaTeX generation
if packages included by default do not suffice, this can be used to specify additional package to use (for multiple packages, enclose every package in its own latex_package tag)
set_body_class
sets the CSS class name for the body, controls page design
some of defined classes are scientific, log, blog, however, currently there's no much difference between these apart from title color, this can be changed in main.css file
set_lang
sets the webpage language
available from 2022.02.26, language to be used for webpage elements (default is English), should be specified as abbreviation, currently only Croatian (hr) is supported, but other translations can be added easily (see lang directory)
no_discussion
controls article comments
when specified and not 0, turns off comments
Chapter Defining title and subtitle updated.Defining title and subtitle
A title and subtitle should be defined like this:
Click here to show the code +
Here, div tag, containing the subtitle, is optional.
UPDATE: This has been simplified. From version 2021.09.22, title and subtitle can be defined without using the spirit tag, using only the title tag:
Click here to show the code +
Writing content
After title definition, article content should be enclosed in a spirit tag, like this:
Click here to show the code +
Use sub1 tag for main chapters and sub2 and sub3 tags for sub-chapters. The no_numbering attribute is optional and it will leave the chapter unnumbered. Attribute ref is
also optional, it creates a reference to the chapter (allowed characters are alphanumeric, underscores and dashes), which can be used in the text as shown above, by prefixing the reference string with \chr_ (the reference will be replaced with chapter
title during page rendering).
Tag sub2 should always follow after sub1, while sub3 should always follow after sub2, otherwise the system might get confused.
For synonyms, just use the = sign, as shown in the example.
Content will be formatted automatically. To start a new paragraph, start the sentence on a new line and make sure there is one empty space character after the last sentence.
Added chapter Text color.Text color
You can use color tag to color text, example:
Click here to show the code +
Color should be specified with the code attribute, as a html color code or named color (as defined by CSS).
If you actually use the word for named color in text, you can omit the code attribute, as in the 3rd example above.
Writing equations
To write equations, use the e tag and mathjax (tex/latex) syntax. Eg. this:
Click here to show the code +
will produce:
$\displaystyle E = {m \over \sqrt{1 - {\beta}^2}} c^2 \tag{1.1}$References
Use a html tag for references, Eg.:
Here, href attribute is used for a link to cited work. The attribute should be present for offline works too, but it should be left empty in that case (href="").
The attribute data-notitle set to 1 signals the engine to use content specified in title attribute when generating references, rather than the content of the a tag (Yukawa, Proca).
From version 2021.10.07, data-notitle is 1 by default if title is specified.
The attribute data-journal can be used to specify additional information that will be used upon generating references (eg. data-journal="Nature 515, 376-378").
To simply add literature to the list of references (without a numbered link) add attribute empty to the a tag.
For regular links add attribute noref with value of 1 to the a tag (noref="1").
Lists and tables
Use ul html tag for unnumbered (bulleted) lists, ol tag for numbered lists and table for tables, eg.:
Click here to show the code +
produces:
item 1
item 2
item 1
item 2
heading 1
heading 2
heading 3
item 1
item 2
item 3
Table \tbl1: Some table
Use a number prefixed with \tbl to create a reference to the table. You can then use it in text like this:
Some items are shown in table \tbl1.
For LaTeX exports, font size for the table can be set with latex-fontsize attribute, the value of which may be one of these:
tiny, scriptsize, footnotesize, small, normalsize, large, Large, LARGE, huge, Huge.
To use LaTeX longtable (table spanning multiple pages) add longtable to the class attribute (eg. class="small longtable").
Column widths for a LaTeX table can be set with latex-width attribute on the appropriate th tag. If this value is purely numeric (eg. "0.6"), a
string \textwidth will be appended to the number.
Updated chapter Notes (boxed content).Notes (boxed content)
To add notes one may use the box tag:
Click here to show the code +
producing:
Sample note.
Note on a red background.
Note on a blue background.
To prevent notes from appearing in LaTeX, add online to the class attribute. To prevent notes from being printed, add noprint to the class attribute.
Figures (images)
Images can be inserted as in the following example:
Click here to show the code +
This produces:
Fig. \fig1: Initialization of life
Fig. \fig3: Correlation of major extinctions (left) with Earth's mantle layers (right)
Similar to table references, here a number prefixed with \fig will produce a reference to the figure, eg. here is a reference to figure \fig3.
The src attribute of img tag contains a link to the image to be shown, while href attribute of the optional a tag may contain a link to the high-resolution source.
The alt attribute of img specifies text that will be shown in case the image cannot be rendered for some reason.
The style attribute is optional and may be used to fine-tune the positioning and size of images.
For LaTeX exports, image width may be specified with the latex-width attribute of the img tag. If this value is purely numeric (eg. "0.6"), a
string \textwidth will be appended to the number.
Added chapter Writing quotations.Writing quotations
To write quotations, one may use state, quote, or song tags. There is no much difference between these. Generated LaTeX for state and quote will be the
same (using quote in LaTeX), while song will be translated to quotation in LaTeX.
Example using state:
This is a quotation.Writing definitions
It is recommended to put definitions into a separate spirit tag of class definitions, eg.:
Click here to show the code +
This way, definitions will be processed by the system so they can be accessed through commands define and explain, even while browsing other webpages of the website.
Small update in \ch (\ch_title).Updates
It is useful to let users know if a webpage has been updated some time after creation. In order to do so, insert the update tag somewhere between the
starting spirit (<spirit>) and ending spirit (</spirit>) tag, like this:
Click here to show the code +
Here the date attribute specifies the date of the update, while content of the update tag specifies the title/description that will be shown in the Change Log.
You may want to add chapter index in the description, in that case use \ch as a placeholder for index (it will be replaced automatically with the index of the chapter
that's below the update tag). The complete list of placeholders that may be used here are shown in the table below.
placeholder
description
Leaving the update tag empty will generate the following description: "Chapter \ch (\ch_title) updated."
\ch_added
will be replaced with: "Added chapter \ch (\ch_title)."
\ch
will be replaced with the index of the chapter that's below the update tag in the document
\ch_title
will be replaced with the title of the chapter that's below the update tag in the document
If you want the placeholders to reference the parent chapter (chapter containing the update tag) instead, add attribute ref_parent to update tag.
Usually, the entry in Change Log will also contain a link to the update, so one may want to position the update tag right above the updated content even if placeholders are not
used. The link generation can be turned off by specifying nolink attribute with a value of 1.
Indexing and menu updates
If the article file (which should have a .html extension) is in a log folder, it will be indexed automatically next time the Log is accessed on the web (although, if
cache is on, the change may not be visible immediately, unless the content of the cache subfolder is deleted).
Other webpages must be manually added to the site menu. For that purpose one should edit /menu.json file and add the webpage file name and title, while conserving the present structure.
Additional info
For the LaTeX export feature, one may want to define a separate spirit tag containing the abstract, before the spirit tag with other content. In that case, simply add
the class abstract to the tag, eg.
Click here to show the code +
Similarly, class postulates may be used for postulates.
Written text will be auto-formatted, along with line breaks. To force a line break (newline), use br tag with noformat attribute (<br noformat>).
Some constants are predefined in universe.js file. Additional constants may be added, as described in that file.
To print the value of constants, one can use the c tag, eg.:
Click here to show the code +
To right align text you may enclose it with the right tag.
Added 'latex_package' tag.Added 'ref_authors' tag.Small updates.Updated Setup and Writing content chapters, added description of no_discussion tag.Added Updates chapter, updated chapters Lists and tables and Figures (images).
