2021.05.27 2021.06.10 Amenoum MATERRA documentation. dox 1 MATERRA Documentation Setup
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.
  1. Copy the contents of the public_html folder to your website root directory (generally public_html),
  2. 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.php DB_USERS constant with a path where you want users database to be stored),
  3. 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:
tagdescriptionadditional notes
log_datedate of article creation
log_updatedate of last updateby default, this is filled automatically and should be left empty
log_mtimefile modification dateby default, this is filled automatically and should be left empty
log_authorauthor namecan 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_descshort description of the workuseful if writing a log type webpage, this will then be used in log index page
log_categorycategoryuseful for log type webpages, used in log index if categories are enabled
log_tagskeywordsused in log index and LaTeX generation (as keywords)
log_keywordswords to highlightcase sensitive, these phrases will be highlighted (bold) in the article
log_clsdocument class, eg. articleused in LaTeX generation
cite_yearyear of publicationused 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_doialternative link to articleused for citations
cite_contriban address for contributionsthis can be a wallet or web (URL) address for support
pdf_linklink to a pdf version of the webpageavailable from 2022.02.26, if present, an pdf icon linking to pdf will be shown in page header
set_body_numberingcontrols auto-numbering of chaptersset to 0 to turn off automatic numbering
set_body_classsets the CSS class name for the body, controls page designsome 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_langsets the webpage languageavailable 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_discussioncontrols article commentswhen 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. 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.:
Click here to show the code +

will produce:

For more consult Yukawa, Proca

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 +

  1. item 1
  2. item 2
heading 1heading 2heading 3
item 1item 2item 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:
Omega egg
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.
Leaving the update tag empty will generate the following description: "Chapter \ch (\ch_title) updated."
\ch_addedwill be replaced with: "Added chapter \ch (\ch_title)."
\chwill be replaced with the index of the chapter that's below the update tag in the document
\ch_titlewill 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. 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).