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 use 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 (ie. 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 (ie. check.settings.inc.php). Each such file affects only specific function or area of the website (ie. 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. 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 (ie. Notepad++) to create and edit webpages. 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
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, ie. 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
set_body_numberingcontrols auto-numbering of chaptersset to 0 to turn off automatic numbering
no_discussioncontrols article commentswhen specified and not 0, turns off comments
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. 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. Writing equations To write equations, use the e tag and mathjax (tex/latex) syntax. Ie. this:
Click here to show the code +


will produce: $\displaystyle E = {m \over \sqrt{1 - {\beta}^2}} c^2$ References Use a html tag for references, ie.:
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 a tag (Yukawa, Proca). 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, ie.:
Click here to show the code +


produces:
  1. item 1
  2. item 2
heading 1heading 2heading 3
item 1item 2item 3
For LaTeX exports, one may define font size for the table by defining the latex-fontsize attribute, the value of which may be one of these: tiny, scriptsize, footnotesize, small, normalsize, large, Large, LARGE, huge, Huge. One may also define column widths for a LaTeX table by specifying the latex-width attribute on the appropriate th tag. If this value is purely numeric (ie. "0.6"), a string \textwidth will be appended to the number. Notes (boxed content) To add notes one may use the div tag with attribute timerel:
Click here to show the code +


producing:
Sample note.
Note on a red background.
Note on a blue background.
Figures (images) Images can be inserted like in the following example:
Click here to show the code +


This produces:
Omega egg
Fig. 2: Initialization of life
Fig. 5: Correlation of major extinctions (left) with Earth's mantle layers (right)
Here, 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, one may also define image width by specifying the latex-width attribute for the img tag. If this value is purely numeric (ie. "0.6"), a string \textwidth will be appended to the number. Writing definitions It is recommended to put definitions into a separate spirit tag of class definitions, ie.:
Click here to show the code +


This way, the definitions will be processed by the system so they can be accessed through commands define and explain, even when browsing other webpages of the website. Updates It is recommended 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 that will be shown in the Change Log. Usually, Change Log will also contain a link to the update, so one may want to position the update tag right above the updated content. 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 automatically indexed next time the Log is accessed on the web (although, if cache is on the change may not be visible immediately, unless the contents of the cache subfolder is cleared). 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, ie.
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, ie.:
Click here to show the code +


Updated Setup and Writing content chapters, added description of no_discussion tag. Added Updates chapter, updated chapters Lists and tables and Figures (images).