asm32

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 is a line, that starts with`;end` keyword. The text to the end of line is ignored.

Example of short source text:

        stdcall CreateContent
        mov     [hContent], eax
        mov     [hIndex], edx

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; ?wink The next cell contains picture. !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. Quotations may contain other formatted text and may be nested.

As a source it looks like this:

  ;quote YONG
  ;quote sleepslep
  ;quote
    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:

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* - but you can use formatting outside the code tags.

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. ?../../../images/icon_smile.gif 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: [http://flatassembler.net]
  
  Another direct link with text: 
    [http://flatassembler.net][flatassembler is the best assembler ever made].

  [1234] http://flatassembler.net
  [flatassembler] http://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: http://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: ?wink

And here we have a block picture: Winnie the Pooh

Another picture with direct address: The same character

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: 31.08.2012 11:43:52


Comments

:)Doge:

Many cool. So Skill. Wow!

:)JohnFound:

Hi, sleepsleep. Welcome on my home server.

:)sleepsleep:

*this seems cool!!*

:)bill gates:

You are the Cool:D

X
Title:
Jump to the top