MSX Assembly Page

MAP document authoring tutorial

On this page I’ll try to explain some guidelines for authoring a document for the MAP. Check the source on Mercurial to see how everything is done in this (and other) pages’ source code.

You can go ahead and get the source code from the MAP Mercurial repository. From there, You can start a new article or add a new resource, or modify an existing one. But keep in mind the social aspect of editing documents, that every article is made and thus ‘owned’ by someone. So although corrections are fine, you probably shouldn’t push significant modifications onto the server without consulting with the author first. Also, if you want to make changes to the style sheet or site structure, drop me (Grauw) a line first :).

If you have push rights to the server, keep in mind that everything you push will be live immediately. Generally speaking, it’s also always useful if someone reviews your changes before they are pushed to the server. Of course, this review can also happen after things are pushed, but because we use Mercurial, if you are unsure about whether something is correct or using the right tags or correctly spelled or whatever, you can easily draft some changes and send them to someone else for review.

Once an article is more or less done, and fit for publishing, think of an appropriate section and category within the site structure, and if one isn’t there yet, add it. Try to keep the organization as logical as possible. Then upload your file into the directory of the section you’ve chosen, and add a link to it in the section overview file (the index.php file in each section directory). If you’ve written the article yourself, or put a large effort in it like translating or transscribing, don’t forget to put your name at the bottom and add a ‘MAP marker’ by adding a <span class="map">MAP</span> to the link, so that people can see that it is authored by us and can exclusively be found on the MAP.

Furthermore, if you publish or update a text (unless it’s a really minor update), please add it to the Last Updates section in main/index.php so that people can easily see what’s been done recently, and also to keep ourselves informed about what the rest has been doing. The updates block is present right after the document title, and if you take a short look at the code, the method of adding an entry should be self-explanatory. Don’t forget to change the date, by the way. If the list becomes too long, you can move a couple of the oldest updates to main/updates-old.php to make it a little shorter. You can also put update blocks in your texts, which can be quite useful aswell. A block inside your text can hold details about the more minor updates not mentioned of the mainpage, and gives a quick overview of the recent changes of that article only. The method of adding such a block is explained in the example updates block below.

Document syntax and formatting

Let’s get started with the layout tags you should use. Every page on this site is made from a combination of XHTML, CSS, and Unicode (UTF-8). Here are links to the HTML documentation, the XHTML documentation, and the CSS 2.1 documentation. The HTML and CSS docs are quite easy to use once you know how they’re structured.

XHTML Strict basically works as follows: it is largely the same as HTML Strict (meaning HTML without any of the tags marked Deprecated), but then written in XML, so every tag has to have an end-tag. If you write a <li>, always close it with a </li>, and the same goes for <p>. Also, don’t write <img src="image.jpg"> and <br> but add a closing / at the end like so: <img src="image.jpg" /> and <br />. The space before the / in singleton tags is important for HTML compatibility. Another requirement of XHTML is that all tags should be lowercase. And on a sidenote, don’t forget that img tags always need an alt="description" attribute. You can check the correctness of your text by running it through the W3C MarkUp Validation Service.

Note that on most browsers, the pages are served as XML and will thus not work if you make syntax errors, so be sure to verify your changes pages in a browser that is not Internet Explorer.

As for a good editor, my preference is Notepad2.

Well then, here goes the layout tags explanation:

<h1>Main topic</h1>

You should put the main topic on the first line of your article, and you can also use it later on to indicate different chapters for example.

<h2>Sub head</h2>

<h3>Sub sub head</h3>

<p>Paragraph with something <em>that needs emphasis</em>, or even <strong>strong emphasis</strong>. Some abbreviation for <abbr title="Disk Operating System">DOS</abbr>, and <dfn>defenestrate</dfn> is a new term that needs to be defined. You can use <i>italics</i> to highlight e.g. file names. And finally <a href="">a link</a> at the end of the paragraph.</p>

Some more tags (look at the code)

Let’s display an unordered list of items now...

And an ordered list...

  1. first item
  2. second item

And a differently ordered list (use CSS!)...

  1. first item
  2. second item

Some preformatted text/tables/code:

                MSB  7   6   5   4   3   2   1   0  LSB
                   +---+---+---+---+---+---+---+---+
   Port #1         |A7 |A6 |A5 |A4 |A3 |A2 |A1 |A0 | First byte
                   +---+---+---+---+---+---+---+---+

	xor a
Label:	cpl
	jp Label

Put inline code fragments between <code> and </code> tags.

And tables must only be used if you want to display a table...

Name of table
row 1 Dude, what does my tattoo say
row 2 Sweet, what does my tattoo say

If you want to render a matrix-like table, add a class="matrix" to the table tag:

Name of table
row 1 Dude, what does my tattoo say
row 2 Sweet, what does my tattoo say

Also, a list of definitions (if you ever need it); Japanese lesson no. 1:

Ittadakimasu
The Japanese say this when they are about to start dinner. In English, it can be somewhat translated like ‘thank you for the food’ (they don’t really have a way of saying this, how impolite!). In Dutch it is simply ‘Smakelijk eten’.

Use unicode!

If you save your documents as Unicode (UTF-8), then you don’t need to use HTML character entity tags (those &something; tags, please don’t use them) for special characters like ë, ×, 日本語, ©, ½, etc. In notepad this can easily be done by selecting UTF-8 as the codepage in the Save As dialog. However, saving as ASCII is fine too, as long as you don’t use any special characters.

However you’ll still need to use &amp;, &lt; and &gt; for &, < and >, because in HTML they are escape characters. They also need to be used inside preformatted (<pre>) tags.

Custom styles

You can also add custom styles to them to either block-level tags like <div> and <p> (p adds an empty line while div does not), or inline tags like <span> and <i> (generally you’ll want to use the span tag). This can be done with a class="" or a style="" identifier. The former refers to predefined classes in the style sheet, while you can specify any CSS2 style in the latter.

~Grauw