MiniMagAsm user manual
This document describes how to setup and work with the content management system - CMS "MiniMagAsm v1.0".
The content management system MiniMagAsm was created to assists the creation of web sites, designed primarily for publication of text information - articles, manuals, tutorials, guides and the like.
The main function of the system is to provide automatic creation of the site navigation and to let the author to create the articles in easy to write, easy to read text format. The lightweight markup language used is similar (but not equal) to markdown and provides readable appearance of the article even in raw form. After formatting the system creates high quality HTML formatted text that is displayed on the web site.
MiniMagAsm engine is portable web application, written entirely in assembly language, using Fresh IDE and FreshLib portable library.
MiniMagAsm can work on either Linux or Windows web server, supporting CGI scripts in native binary form for the target platform (ELF executable for Linux and PE for Windows).
Every hosting package claiming "C++ CGI" should be OK.
The main advantages of the MiniMagAsm CMS are:
Provides uniform design and appearance of all articles. The author provides only the content.
Easy publication - the author only uploads the text files to the web server, then the system automatically includes the new article in the navigation system and allows the visitors to read it.
Comfortable hierarchical navigation system that supports content arrangement in unlimited tree structure.
Plain text format of the published articles, readable and editable in its original form.
Because of its very small size (roughly 10KB), its assembly powered speed and its small memory use, MiniMagAsm loads the server insignificantly and can work even on small machines with very little memory and slow processors.
The use of lightweight web server is recommended in this case.
1. Compiling MiniMagAsm
As long as MiniMagAsm is in heavy development, I will not provide downloadable distribution for now.
If you want to hack the sources and to try and use MiniMagAsm, you have to download the sources and compile them. It is not so hard though.
First, download and install Fresh IDE from the Fresh main site.
Second, download the latest version of FreshLibDev branch from the Fresh source repository. Read about it FreshLib project page.
Set Fresh directory alias lib to the updated directory of FreshLib. (follow Options|IDE options|Aliases menu)
Download the latest MiniMagAsm version from the MiniMagAsm source repository.
Open the file MiniMagAsm.fpr from Fresh and set the prefered target os in the project manager.
Compile using menu Project|Compile or by pressing Ctrl+F9. The only possible errors are if you didn't set properly the path to the FreshLib library in the %lib% directory alias.
The compiled file index.cgi is located in the subdirectory www/.
There are two more files to be compiled: Feedback.fpr and Save.fpr They are compiled in the same way as MiniMagAsm.fpr
The compiled file save.cgi and save.inc (the template file) should stay in the password protected directory save/ in order to allow article editing only for authorized people.
Now you can set your web server to the directory www/ and to browse the MiniMagAsm site.
2. The design of the site
MiniMagAsm supports unified design of the site through the easy template engine and three files with styles sheets: common.css, engine.css and editor.css.
The user can easy edit any of these tree files in order to customize the web site for his own needs.
Regardless of its simplicity, this system is very flexible and allows unlimited freedom for the web designer to express his individuality.
3. Installation
The installation of MiniMagAsm is very simple. The files you need are:
index.cgi - compiled for the needed OS. In Linux you must set the file
permissions to 755 in order to allow its execution.
template.inc - you may want to make some edits in this file in order to
implement you own design.
engine.css - contains the CSS styles needed for the proper work of the
navigation menues of the site. You can edit it in order to change the appearance,
but be careful to not affect the behaviour.
common.css - contains the CSS styles for the common site appearance.
They can be edited in order to design the site appearance.
editor.css - contains the CSS styles for the article editor.
feedback.cgi - the script that allows visitors to comment articles in the site.
feedback.inc - template file for the feedback save message and redirection.
/save/save.cgi - script that saves the edited articles to the disk.
/save/save.inc - template file for save.cgi
NOTE: The directory save/ must be password protected with .htacces file or other server
provided authorization protection in order to prevent article editing from unauthorized persons.
The engine of MiniMagAsm expects some images to be in the directory "images" in the root directory. They are:
images/anchor.gif - icon for the user defined anchor inside the documents.
images/document.gif - icon for the articles in the main menu.
images/folder.gif - icon for a closed folder in the main menu.
images/folderopen.gif - icon for an open folder in the main menu.
images/spacer.gif - transparent picture 16x16 pixels used as an invisible spacer.
images/toc.gif - icon for the back links to the table of contents in the headings.
You can change these images in order to change the design of the site.
content/title.ttl - text file with one line short name of your site.
content/index.txt - the default home page of your site. This is MiniMagAsm
formatted text file, that will be displayed by default.
4. Web site elements
4.1. Articles
The articles in MiniMagAsm are plain text files, containing some text markup, that will not affect the readability of the text.
All articles are saved in the directory "content/" of any of its subdirectories. The user can create arbitrary count of them in order to classify the documents in categories.
The web site has a hierarchical structure of the navigation menu, automatically created, following the structure of the directory "content/". Every file with extension ".txt" from these subdirectories is seen as an article. The first line of the text file is used as the name of the article in the navigation menu and this line is not included in the text of the article rendered on the site.
The directories with a name beginning with "." or "_" are not included in the navigation menu. They are for private use and documents from these directories can be displayed only following direct link from the article text.
Every subdirectory of the articles tree must contains a file, named "title.ttl", which is a text file containing the name of the directory for the navigation menu. Only the first line of this file is read.
The markup language used, supports formatting for headings, paragraphs, unnumbered lists, images, tables, programming source code, block quotes and several inline text formats - such as bold, italic, underline and strikeout fonts and inline source code.
The headings structure of the article is used for creation of the table of contents of the article in order to make navigation inside the long articles easier for the reader.
4.2. Template
The template of the site contains normal HTML file, that forms the common structure of the web site. The template contains some variables that will be replaced with the content, generated by MiniMagAsm when it renders some page.
The variables are enclosed in $ char. The current version of the system supports following variables:
$description$ - contains the description of the page, defined inside the article with
the `;description` command;
$keywords$ - the keywords of the article, defined in the text with the `;keywords`
command.
$title$ - contains the title of the article, defined in its first line.
$menu$ - contains the text for the main navigation menu.
$index$ - contains the text with the document table of contents.
$maxblock$ - contains a fake block of text, that represents the maximal
width of the site navigation manu. This way, the width of the
navigation menu will remains the same, regardless of the
collapsed or expanded directories. The template should hide
this text, but in order it will exists a as width.
$content$ - the article HTML text, formatted by MiniMagAsm.
$runtime$ - the time in (ms) that the script used to render the article.
4.3. CSS styles
Not written yet...
5. Article elements
5.1. Headings
The heading is considered the line that starts with "#" character. The headings are hierarchical and use the HTML tags from H1 to H6.
The level of the heading is determined by the number of the "#" symbols at the beginning of the line - from 1 to 6. If the user use more than 6 "#"s, H6 is used.
When MiniMagAsm renders the document in HTML it uses the headings to construct the document table of contents. This TOC then is displayed in the page, depending on the site template.
Also, after the heading, hyperlink is appended, that provides easy return to the table of contents.
5.2. Paragraphs
The start of a paragraph is considered the first line, containing text after an empty line.
Empty line is a line that contains only space and tab characters - i.e. line that appears empty.
The paragraph ends when it reaches an empty line or at the beginning of some other block element - heading, source code, quotation, table or image.
5.3. Horizontal rule
The horizontal rule is generated if the line starts with at least four "-" symbols.
The following text on the line will be ignored. The horizontal rule element behaves like an empty line for the remaining elements of the text.
Here is an example:
Some text paragraph
---------- Horizontal rule element
Some other paragraph.
And how it will be rendered in the text:
Some text paragraph
Some other paragraph.
5.4. Unnumbered lists
If the first character of the paragraph, other than white space is "*", the paragraph is formatted as a bullet list item.
The text looks like this:
This is normal paragraph,
containing two lines of text.
* This is bullet list item.
* This is another bullet list item.
containing more that one line of text.
And this is another regular paragraph.
This text will be rendered as:
This is normal paragraph, containing two lines of text.
This is bullet list item.
This is another bullet list item. containing more that one line of text.
And this is another regular paragraph.
5.5. Programming source code
The start of the source code is line beginning with ;begin keyword.
The text to the end of the line is ignored in the current version of
MiniMagAsm.
Nevertheless, to use it in the form ;begin langname is encouraged, where
langname is the name of the programming language of the source.
In the future versions, syntax highlighters might be implemented that to use this information.
The end of the source code is a line, that starts with ;end keyword. The text
to the end of line is ignored.
Example of short source text:
;begin fasm
stdcall CreateContent
mov [hContent], eax
mov [hIndex], edx
;end
A very long source code will be enclosed in the limited size container, with scroll bars:
include "%lib%\compiler\executable.inc"
_BinaryType console
include '%lib%/macros/allmacros.inc'
include '%lib%/equates/allequates.inc'
GlobalAPI equ unicode
_CodeSection
options.ShowSizes = 1
options.DebugMode = 0
options.AlignCode = 0
include '%lib%/simpledebug/debug.asm'
include '%lib%/system/process.asm'
include '%lib%/system/memory.asm'
include '%lib%/system/files.asm'
include '%lib%/system/environment.asm'
include '%lib%/data/arrays.asm'
include '%lib%/data/strlib.asm'
include '%lib%/data/markdown.asm'
include 'minimag.asm'
uglobal
fParentVisible dd ?
StartTime dd ?
hPath dd ?
hQuery dd ?
hPageName dd ?
hSubmenuHash dd ?
hMenu dd ?
hMaxWidth dd ?
hContent dd ?
hIndex dd ?
endg
start:
stdcall GetTimestamp
mov [StartTime], eax
InitializeAll
stdcall InitScriptVariables
stdcall CreateContent
mov [hContent], eax
mov [hIndex], edx
stdcall CreatePageMenu, cContentDir, -1, [hSubmenuHash], [hPageName], fParentVisible
mov [hMenu], eax
mov [hMaxWidth], edx
stdcall WriteTemplate, sHTMLTemplate, [STDOUT], TestVarCallback
push eax
FinalizeAll
stdcall Terminate
iglobal
sHTMLTemplate:
file "template.inc"
.size = $ - sHTMLTemplate
dd 0
endg
_EmbededImports
_DataSection
IncludeAllGlobals
5.6. Tables
The tables are defined with the keyword ;table.
In the table, every paragraph is considered as a table cell.
The new row in the table begins on the row beginning with ";" and containing at least
four "-".
Here is some example:
;table
The *first* row, _first_ cell of the table contains some inline formatting.
The second cell in the table; [?wink] The next cell contains picture.
[!picture]
;---------------------------------------------
(2, 2)The second row, first cell.
This paragraph have collspan=2; rowspan=2;
The second row, second cell
;--------------------------------------
The third row, third cell. There is no cells 1 and 2 because the first cell from
the second row, spans in columns and rows.
;end table
And rendered:
| The first row, first cell of the table contains some inline formatting. | The second cell in the table;  The next cell contains picture.
|
|
| The second row, first cell. This paragraph have collspan=2; rowspan=2; | The second row, second cell | |
| The third row, third cell. There is no cells 1 and 2 because the first cell from the second row, spans in columns and rows. | ||
5.7. Block quotes
The quotations are enclosed between the lines beginning with ;quote for the
start of the quote and ;end for the end of the quote.
The text after the keyword ;quote and the end of the line is used as a title of the
quotation block.
Quotations may contain other formatted text and may be nested.
As a source it looks like this:
;quote YONG
;quote sleepslep
;quote YONG
It is true. For one thing, no matter how hard
I try, I am unable to free sleepsleep from
religious entanglement.
;end quote
because you unwillingness to let go, or to accept,
you see, that is the root cause.
and you see, how somebody, something could inflict
pain on you... they just need to stand there and
let you judge them and you will feel the pain.
;end quote
You are right. Maybe it is time for me to let go!
How about you? Are you willing to let go of your
religious entanglement... and savings? :roll: :wink:
;end quote
Rendered it looks like:
YONG
sleepslep
YONG
It is true. For one thing, no matter how hard I try, I am unable to free sleepsleep from religious entanglement.
because you unwillingness to let go, or to accept, you see, that is the root cause.
and you see, how somebody, something could inflict pain on you... they just need to stand there and let you judge them and you will feel the pain.
You are right. Maybe it is time for me to let go!
How about you? Are you willing to let go of your religious entanglement ... and savings? :roll: :wink:
Note: I got this text from the HEAP section of the FASM forum - great place to learn assembly language programming.
5.8. Text formatting
The text in the document can be formatted with use of markers, surrounding the formatted text. The markers are the same for the beginning and the end of the specially formatted text.
To be a valid markup character, the start marker should be preceded by a white space character and the end marker should be followed by a white space character. Otherwise, the markers are considered a part of the text and no formatting is done.
The supported markers for the current version are:
"*" for bold text
"/" for italic text
"_" for underline text
"-" for strikeout text and
"`" for inline source text.
Examples:
*Bold text*
/Italic text/
_Underline text_
-Strike out text-
_-*/Underline, bold italic and strikeout text/*-_
`Inline source code`
`*Bold, inline source code*` - formatting doesn't work inside the code tags.
-`*Bold, inline source code*`- - but you can use formatting outside the code tags.
Here is how this example is rendered:
Bold text
Italic text
Underline text
Strike out text
Underline, bold, italic and strikeout text
Inline source code
*Bold, inline source code* - formatting doesn't work inside the code tags.
*Bold, inline source code*
And here is an example for "_" character used without causing formatting: "MB_CANCEL"
5.9. Links and Images
There are several ways the one can create links in a MiniMagAsm document. There are two types of links - reference links and inline links. In the reference links, the author defines the link address outside of the main text flow and then reference to the link by its ID. The inline links address is entered directly in the text.
The general syntax for the link used in the text is:
[linkID][Linktext]
or
[linkID]
The Link text is optional. If there is no link text, the link ID will be placed in the text. The linkID can contains arbitrary characters, except "]" which ends the linkID definition.
Note, that the link can not be put at the begining of the line, because it will be considered definition, not a reference.
Link definitions begins at the first position of the line and have following syntax:
[linkID] address_of_the_link
There are several types of linkID definitions, depending on the first char of the linkID.
Local links are defined when the first character of the linkID is "#". In this case, the link definition is not stripped from the text, but an anchor with the given linkID will be created.
Footnotes are defined when the first characted of the linkID is "^". In this case, the
definition line is also not stripped from the text, but all the footnotes are grouped at
the end of the document and when referenced, the link to the footnote is generated.
Images are defined when the first character of the linkID is "!" or "?". In this case, the
LinkText from the reference will be used as an alt text for the image. The "!" prefix defines
a block type image, horizontally centered on the page. The "?" prefix defines inline image,
that can be included inside the text. 
like this.
any other first char for the linkID will generate normal hyperlink.
if there is no defined link with the given linkID, the linkID itself is accepted as a link address. This approach allows the use of inline links definitions, instead of reference links. The rules for the inline links are the same with that difference, the linkID must contains directly the address of the link.
Also, there are several types of link addresses as well:
If the link begins with protocol identifier - protocol://, the link is "external" and will
be included literally.
if the link begins with "#" sign, it is considered "document internal" and also will not be processed further.
if the link doesn't fall among previous cases, it is considered "site internal" and here we have two cases:
case a: If the link points to the .txt document, then a prefix index.cgi?page=%document_path% will be inserted
before the link address. Also, if possible, the engine attempts to resolve back link directories in the
path ("..") in order to normalize the path to the linked document.
case b: If the link points to document with extension other than .txt - then only %document_path% will be inserted as a
prefix and the same processing for resolving back link directories will be done.
Note: Even if the link normalizing from the previous two points fail to resolve the back link directories in the link address, MiniMagAsm will not accept site-internal links with ".." inside. If such link is passed as a "page=" argument, the default home page "index.txt" will be returned instead of requested page. (maybe, it is even more correct to return "404 Not Found" error instead).
Here you can see the source for various types of links:
This is [1234][link to flatassembler.net]
This is a link to [flatassembler] as well.
This is direct link to the address: [https://flatassembler.net]
Another direct link with text:
[https://flatassembler.net][flatassembler is the best assembler ever made].
[1234] https://flatassembler.net
[flatassembler] https://flatassembler.net
Some internal link: [#here][Jump inside the document.]
[#here] This is some paragraph, that have to be pointed by
internal links.
Now, let use some smiles: [?wink]
[?wink] ../../../images/icon_wink.gif
And here we have a block picture: [!picture][Winnie the Pooh]
[!picture] demopicture.jpg
Another picture with direct address: [!demopicture2.jpg][The same character]
Link to another page in the site: [tfal.txt]
Link to document two directories back: [../../1_FreshSite/articles/1_tips.txt]
And how these links are rendered:
This is link to flatassembler.net
This is a link to flatassembler as well.
This is direct link to the address: https://flatassembler.net
Another direct link with text: flatassembler is the best assembler ever made.
Some internal link: Jump inside the document.
This is some paragraph, that have to be pointed by internal links.
Now, let use some smiles:
And here we have a block picture:
Another picture with direct address: 
Link to another page in the site: tfal.txt
Link to document two directories back: ../../1_FreshSite/articles/1_tips.txt
5.10. Metatags
The words ;keywords and ;description at the beginning of the line creates
meta-tags definition lists. ";keywords" adds the remaining of the line
to the $keywords$ template variable and ";description" do the same for
$description$ template variable.
The template then uses these variables as a META tag content.
5.11. Comments
Every line that begins with ";" and the following text is not
recognized as a keyword ;begin ;quote ;keyword ;description
is considered a comment and will not be rendered at all.
In order to prevent future conflicts with new introduced keywords, it is
recomended to precede the comments with double semicolon chars: ;;.
5.12. Browser window title bar.
The title in the title bar of the Windows application contains the name of the site (from the file "content/title.ttl) and the name of the current article.
Last modified on: 28.01.2018 12:13:51
John Found ( 28.02.2016 07:32:45 UTC ) :
Diego ( 27.02.2016 01:06:30 UTC ) :
Mikal: