The Azimuth Project
How to

An easy introduction to the elementary basics is here:

The following article provides more details. See also the FAQ.

Contents

Getting Started

How to use a wiki

Hit “edit page” to see how pages are coded. Use the Sandbox to warm up. They key point is that links to other pages are placed in [[double brackets]].

There is no feature to preview your edits. Instead, submit them and then edit again. Two successive submissions with the same signature and made within 30 minutes of each other count as one in the record, so don't worry about cluttering up the database with multiple submissions in a row.

How to start a new page

You do this in three steps, the first of which may have already been done:

  1. Create a preliminary link (represented by a question mark) by editing a current page and putting the name of the new page in double square brackets. (You can do this in the Sandbox if there is no better place, but probably you want to do this in context on a relevant page that should link to your new page.)

    Watch out: the name of a page is case sensitive. We like to have our pages begin with a capital. So capitalize the first word in your link, even if doesn’t come at the beginning of a sentence. Use the optional wiki link syntax: [[New page name|new page name]], this will create a page with the name using the first part of the link “New page name” but use the link text in lowercase “new page name.” This will make life a bit simpler for the rest of us.

  2. Click on the question mark to begin editing the new page. This will bring up a blank edit box for the text for your new page. Note: The page will not actually be created until you hit Submit.

  3. If you want a template to make your page look like most of the others, copy the template source from the Template page into the blank edit box for your new page. Don’t worry. Most of the time you can just copy the template source code directly, change a few items, and start writing.

Note to new contributors

When you edit a page, you can (and should) put your name (with normal capitalisation and spacing) in the box after ‘Submit as’. If you don't, then your contribution will be credited to the AnonymousCoward.

Once you edit a page for the first time, your name will appear at the bottom, grayed out with a question mark since there is no page with your name yet. You may take this as an invitation to create a user page and tell us about yourself. But if you don’t want to or don’t have the time right now, you can forget about this. If you just want to show up on category: people, then you make a page containing only ‘category: people’ (or someone else may do this for you).

To create your user page, simply click the question mark that appears next to your name at the bottom of the page after making a modification and add content to the edit box that appears. If you’d like to make a user page prior to modifying an existing page, you can do so by making some trivial modification to the Sandbox, which will put your name at the bottom of the page where you can click the question mark. (Or hack the URL.)

How to merge pages

Suppose we have two pages, named ‘A’ and ‘B’, and you decide that they ought to be merged into a single page, say ‘A’. Of course, you need to edit ‘A’ to contain the material from ‘B’ and make a coherent whole, but there are also some technical aspects. We do not want to simply delete ‘B’, since it contains the history of the edits to that page, which might turn out to be useful. However, we do want these two things:

  1. links to ‘B’ ought to send the reader to ‘A’;
  2. the old page ‘B’ should be clearly marked as archive material.

We accomplish (1) with a redirect; we accomplish (2) with a page move?. If you do this too carelessly, then it will not work; in the worst case, links to ‘B’ will still go to the archive page, and that will look to the casual reader like a regular page. So follow these steps:

  1. Edit ‘A’ so that it looks how you want, and add the line ‘[[!redirects B]]’ to the bottom. Submit.
  2. Open ‘B’ for editing.
  3. Click the checkbox ‘Change page name.’, which will bring up a new field ‘New name:’.
  4. In that field, add ‘ > history’ to the end, so that ‘B’ becomes ‘B > history’.
  5. Click in the big edit box, which will automatically add ‘[[!redirects B]]’ to the top.
  6. Change the line ‘[[!redirects B]]’ into ‘< [[B]]’ instead.
  7. Delete everything else (consisting of the material that you already merged into ‘A’).
  8. Submit.

The result is that links to ‘B’ will redirect to ‘A’ (not to ‘B > history’). And if anyone does land on ‘B > history’, all that they will see is ‘< B’ with a link to ‘B’ (properly redirected to ‘A’).

Page naming conventions

These are not set in stone, but we’re following them for now. Changing page titles results in unnecessary work for the lab elves, so you should try to follow these if possible (or dispute them if not). It is most important to follow these in links to pages that don’t yet exist, so that the pages will be created at the correct title (and only once).

  • Page titles should contain only ASCII characters.

    • Reason: It’s possible to put non-ASCII characters in a name, but not ones generated by iTeX or &…; character entities, so this can be difficult, depending on your browser. To keep things easy, therefore, use only ASCII characters in links.
    • With the introduction of redirects to Instiki, non-ASCII links can be made to point to the ASCII page.
  • Page titles should be singular nouns or noun phrases, with only the first letter capitalized (unless there’s a darn good reason).

    • Examples: Use [[Dead zone]] instead of [[dead zone]], [[Dead zones]] or [[dead zones]]. On the other hand, it’s fine to capitalize every word in people’s names (like [[David Tweed]]) or names of organizations (like [[International Energy Agency]]). With book titles, follow the usual capitalization practices: for example, [[Without the Hot Air]].
    • Tricks: To produce a link ‘dead zones’ that goes to the Dead zone page, use [[Dead zone|dead zones]].
    • Reason: We want only one page on a given concept, regardless of variations in grammar.
    • Again, thanks to the use of redirects, dead zones now gets you to Dead zone without needing to type [[Dead zone|dead zones]]. Feel free to add redirects to make your life easier.
  • Except when there’s a darn good reason, use standard American English spelling conventions.

    • Reason: Many articles are written by John Baez, who uses American English spelling.

References

Referring to a paper in a journal

Here’s how to refer to a paper. Write something like this:

* E. Rignot, _et al._, [Recent Antarctic ice mass loss from radar interferometry and regional climate modelling](http://www.phys.uu.nl/~broeke/home_files/MB_pubs_pdf/2008_Rignot_NatGeo.pdf), _[Nature Geoscience](http://www.nature.com/ngeo/journal/v1/n2/full/ngeo102.html)_ **1** (2008), 106–110.

which produces this:

Note:

  • Include a clickable link on the paper’s title if and only if clicking on that link will give a free copy of the paper.

  • Include a clickable link on the journal’s name if and only if clicking on that link will take you to the paper on the journal’s website (which may not be available for free).

  • If the paper is not on arXiv use a doi link like this whose target is: http://dx.doi.org/10.1038/ngeo102 and the general format is: http://dx.doi.org/doi Most journals list the doi for their articles on the article’s website; however, you can use crossref as a doi lookup tool if you can’t find the doi for a given article. One reason for using these links is that they are more likely to be stable than the direct journal website links.

It goes like this:

  • Firstname Lastname, Firstname Lastname and Firstname Lastname, Papertitle, JournalTitle Volumenumber (Year), firstpage-lastpage.

If you can’t stand typing all the author’s names, use et al. But someday you will coauthor a paper, and then you’ll hope people include your name when referring to this paper!

Referring to a book

Here’s how to refer to a book. Write something like this:

* James Lyle Peterson, _Petri Net Theory and the Modeling of Systems_, Prentice Hall, New York, 1981.

which produces this:

  • James Lyle Peterson, Petri Net Theory and the Modeling of Systems, Prentice Hall, New York, 1981.

It goes like this:

  • Firstname Lastname, Firstname Lastname and Firstname Lastname, The Book Title, Publisher, Locationofpublication, Yearofpublication.

If the book is freely available, you can make the book’s title into a clickable link, as for journal articles.

If the book is not freely available, use the wikipedia ISBN book sources link like this, whose target is:

http://en.wikipedia.org/wiki/Special:BookSources/9780136619833#Online_text

The general format is:

http://en.wikipedia.org/wiki/Special:BookSources/ISBN#Online_text

Be sure to remove any dashes from the ISBN or the link will not work. Following these links automatically generates links out to many of the book sources on the internet.

Referring to Wikipedia or Scholarpedia

To refer to Wikipedia, write something like this:

* [Petri Net](http://en.wikipedia.org/wiki/Petri_net), Wikipedia.

which produces this:

Scholarpedia articles also have ‘curators’:

* Carl Adam Petri and Wolfgang Reisig, [Petri net](http://www.scholarpedia.org/article/Petri_net), Scholarpedia.

produces

  • Carl Adam Petri and Wolfgang Reisig, Petri net, Scholarpedia.

Referring to a website

If the website has authors, use their names. Type something like this:

* Wil van der Aalst, Vincent Almering, and Hermen Wijbenga, [Interactive tutorials on Petri nets](http://www.informatik.uni-hamburg.de/TGI/PetriNets/introductions/aalst/).

which produces

If the website has no authors but gains credibility from being based at a reputable location, you can name the location. Type something like this:

* [The Petri Nets World](http://www.informatik.uni-hamburg.de/TGI/PetriNets/), Department of Informatics, University of Hamburg.

which produces:

For the homepage of an organization or person, you can type something like this:

* [John Baez](http://math.ucr.edu/home/baez/), homepage.

which produces

Clickable citations

Suppose you want to say:

The Shannon entropy (Shannon1948) of a probability measure pp on a finite set XX is given by…

and make it possible the reader to click on the citation “(Shannon1948)” and go straight to the correct reference at the of the wiki page, namely:

If you don’t understand what I mean, click on “(Shannon1948)” and you’ll see.

To achieve this effect, just type:

The Shannon entropy ([Shannon1948](#Shannon1948)) of a probability measure $p$ on a finite set $X$ is given by...

in the article itself, and

* C. E. Shannon, [A mathematical theory of communication](http://cm.bell-labs.com/cm/ms/what/shannonday/shannon1948.pdf), _Bell System Tech. J._ 27 (1948), pp. 379--423.

{#Shannon1948}

in the bibliography. It’s important that {#Shannon1948} appear at the beginning of a new line, all by itself.

How To Write a Blog Entry

Suppose you want to write an article for the Azimuth Blog called ‘Overfishing’. First, check out Blog articles in progress and look at some examples of existing articles. Go to an article and click ‘Source’ down at the bottom to see what the source code looks like. Also think about the style: articles should be clear and simple, and preferably a bit fun. You can assume they’ll be read mostly by scientists and engineers - but not people who are already experts in your favorite subject!

Then:

  1. Start by creating a new entry on Blog articles in progress. Copy the format of the existing entries.

  2. Create a new wiki page called (in this example) “Blog - overfishing”. Start writing your blog entry on that page.

  3. Go to the Azimuth Forum and start a discussion called “Blog - overfishing”. Let us know a bit about your article, so we can start looking at it and making suggestions. If you’re not a member of the Azimuth Forum, consider joining it.

  4. When you’re done, make sure John Baez knows, so he can give your article a final edit and post it.

It takes some work to convert a blog article written on the wiki to one that works on the blog. But some of the most annoying chores can be eliminated if you follow these rules. The most important one is first:

For blog articles use HTML, not Markdown

You don’t need to write your article using full-fledged HTML, with <p> at the start of each paragraph and all that. But if you want to save us some time, whenever you’re tempted to use a Markdown command for formatting, please use the equivalent HTML command.

Why? Because in general both HTML and Markdown work on the Azimuth Wiki, while only HTML works on the blog.

There are some annoying exceptions: for example, an <a href = , <i> or <b> command at the very beginning of a line of text does not work correctly on the Wiki. Presumably this is a bug. You can work around this by starting the line with UGH - A BUG. This is easy to remove when then the article is transferred to the Azimuth Blog.

Some examples of how to use HTML instead of Markdown:

  • replace all uses of * to make a bullet symbol by &amp;bull;

  • replace all uses of _ _ to make italics by <i> </i>

  • replace all uses of ** ** to make boldface by <b> </b>

  • replace all uses of > to make a quotation by <blockquote> </blockquote>

  • make links using <a href = ""> </a>

For blog articles, format displayed equations nicely

It will save time if displayed equations are written as

$$ E = mc^2 $$

without linebreaks and with no space after the very last $, rather than say

$$

E = mc^2

$$

Why? The reason is that for a Wordpress blog we need to convert these equations to

$latex E = mc^2 $

and this is easier if you do what I suggest!

For blog articles, use standard TeX

The wiki uses some clever tricks that don’t work on other TeX installations. So, for blogging, please avoid these.

For example: for math operations in roman font, when composing blog articles on the wiki, please write something like

$ \mathrm{ad}_x$

not

$latex ad_x$

Why? On the wiki an uninterrupted string of letters in dollar signs produces roman text:

$ad_x$

gives

ad xad_x

while

$a d_x$

gives

ad xa d_x

This is a special feature of Instiki. But on the blog, as in ordinary TeX, it doesn’t work that way! There

$latex ad_x$

and

$latex a d_x$

both give

ad xa d_x

while

$latex \mathrm{ad}_x$

gives

ad xad_x

which is what you want.

For blog articles, do references nicely

Please use the correct format for references to books, articles and the like. For the wiki, the rules are written down here.

However, the blog uses html but not markdown, while the wiki uses both. So, it can never hurt to use html (or at least hardly ever). That means instead of writing something like this:

* E. Rignot, _et al._, [Recent Antarctic ice mass loss from radar interferometry and regional climate modelling](http://www.phys.uu.nl/~broeke/home_files/MB_pubs_pdf/2008_Rignot_NatGeo.pdf), _[Nature Geoscience](http://www.nature.com/ngeo/journal/v1/n2/full/ngeo102.html)_ **1** (2008), 106–110.

you should write this instead if you’re writing a blog article:

* E. Rignot, <i>et al.</i>, <a href = "http://www.phys.uu.nl/~broeke/home_files/MB_pubs_pdf/2008_Rignot_NatGeo.pdf">Recent Antarctic ice mass loss from radar interferometry and regional climate modelling</a>, http://www.nature.com/ngeo/journal/v1/n2/full/ngeo102.html"><i>Nature Geoscience</i></a> <b>1</b> (2008), 106–110.

The result will look like

For blog articles, make figures 450 pixels wide

For example:

<div align="center"><a href="http://math.ucr.edu/home/baez/mathematical/stochres_midnoise.png"><img width="450" src="http://math.ucr.edu/home/baez/mathematical/stochres_midnoise.png" /></a></div>

This makes the figure 450 pixels wide, but lets the reader get a big version just by clicking on it.

Special Typesetting Features

How to leave comments and questions

If you want to make a comment or question about a page without changing its main content, then edit the page and put your comment or question in a query block as shown in this example:

+-- {: .query}
How do I ask a question?
=--

which produces

How do I ask a question?

Note that a query block should be less permanent than the rest of the page; once your comment is addressed or your question is answered, you can probably remove your query block.

If you want to ask a question of a specific person, then you can place a query block on their user page (which is just a page whose title is their name). You should be able to find all user pages [[people|here]]

If your comment or question is more general than a specific page or person, then try the Azimuth Forum. After you [ForumHelp|join the forum], you can start a new discussion — it’s best to do it under the category ‘Questions’.

Over time, answers to important questions will be migrated to [[HowTo|this How To]] and the [[FAQ]]. As this is a Wiki, if you find an answer to your question and feel it should be added to one of those pages, then please do it!

How to make a standout box or quote box

If you want to make some text stand out (an important fact, or slogan), you can do it using a standout box:

+-- {: .standout}
_The significant problems we have cannot be solved at the same
level of thinking with which we created them._ -- Albert Einstein  
=--

will produce

The significant problems we have cannot be solved at the same level of thinking with which we created them. – Albert Einstein

If you want to quote someone, you can use a quote box:

As old Albert once said,
+-- {:  .quote}
The significant problems we have cannot be solved at the same
level of thinking with which we created them.  
=--

will produce

As old Albert once said,

The significant problems we have cannot be solved at the same level of thinking with which we created them.

How to include one page within another

If you have some material at a page called foo that you want to include directly in pages called bar and baz, then type

<nowiki>[[!include foo]]</nowiki>

in bar and baz. For an example, see how [[contents]] is included at the tope of this page. Also see how [[contents]] itself has been formatted so that it will appear as a sidebar when included.

Besides such sidebars that appear in many pages, you can also use inclusion to put in something that contains a bunch of ugly code (such as raw SVG) without mucking up the rest of the page. That is, you put your messy code in bar/foo and then put

<nowiki>[[!include bar/foo]]</nowiki>

in bar. Note that this is for something that, logically, should appear within bar itself, which is why bar appears in the name of the included page.

Note that the included page goes directly in where it is called with no surrounding whitespace. This can mean that formatting rules are broken on the include. For example, if the included file starts and ends with a div tag and is included with no surrounding blank lines then this breaks the rules and will generate an error.

How to use redirects

See [[redirects]].

How to include dollar signs

Dollar signs mark the beginning and end of equations in LaTeX. In full-fledged LaTeX one can get an actual dollar sign using

\$

but this does not work here. At present the only known way to produce a dollar sign to use the HTML code

&#36;

which produces

$

Since the mechanism for inserting links uses parentheses to delimit the link, it’s not obvious how to put parentheses actually in the link itself. Since Wikipedia uses them a fair bit, it’s worth knowing how to put them in. The trick is to use the URL codes rather than the actual characters. URL codes are generally used to send “unsafe” characters in URLs (safe characters are a-zA-Z0-9$-_.+!\*'(),). Although parentheses are actually “safe”, due to their special meaning for the markdown filter, to put them in URLs here they need to be treated as “unsafe”. URL codes have the syntax %hex where hex is the index of the character in the ASCII character set represented as a 2-digit hexadecimal. Wikipedia (among other places) has a table of the character set from which one can read off the required hexadecimal. In particular, we see that ( is %28 and ) is %29. Thus

[Monad (category theory)#Monads and adjunctions](http://en.wikipedia.org/wiki/Monad_%28category_theory%29#Monads_and_adjunctions)
produces

Monad (category theory)#Monads and adjunctions

When you create a section header, you can add an HTML ‘anchor’ tag to it with the following syntax:

 ## Heading {#anchorname}

Then you can make a link to that section, from that page or from another one, with the syntax:

 [a link](Pagename#anchorname)

Here ‘Pagename’ is the name of the page your ‘anchor’ is on.

You can also link to this location from outside the Azimuth Wiki using the URL:

  http://www.azimuthproject.org/azimuth/show/Pagename#anchorname

For example, to link from the Azimuth Forum to a subsection of an Azimuth Wiki page you can do this:

  [a link](http://www.azimuthproject.org/azimuth/show/Pagename#anchorname)

Even if you don’t add an HTML anchor tag to a section header, it is still possible to create a link to that section, at least if your page has a table of contents, since every section on the page is automatically assigned an HTML anchor by Instiki. However, using such links is not encouraged, since the automatically generated anchor names will change whenever the page is rearranged and go away if a manual anchor name is added, which will cause such links to break.

When you write a numbered theorem, you can also simultaneously create an anchor by writing:

 +-- {: .num_theorem #theoremname}
 ###### Theorem
 ...
 =--

And then you can link to it in the same way:

 [see this theorem](/nlab/show/some+page#theoremname)

When you link to a theorem on the same page, however, it’s better to use the syntax:

 see Theorem \ref{theoremname}

(which inserts the number, as well as creates a hyperlink) since that will also work properly when the page is exported to LaTeX.

How to add an automatically generated table of contents

Insert the symbols

 * tic 
 {:toc}

(including the line break!) at the position where the table of contents is to appear. Its items will be the section headlines marked by

 # top leven headline #


 ## second level headline ##



 etc.

Instead of “tic” (which is just a joke inspired by “toc” for “Table Of Contents”) here you can write anything you like: this line will not be displayed but is still required. A useful thing to type is for instance

 * automatic table of contents goes here
 {:toc}

since this will indicate to everyone looking just at your source code what the command will accomplish.

It is also important that the section headings not contain anything that shouldn’t go in the table of contents. Whilst formatting is allowed, wiki-links are not (since then the entry in the table of contents would be double linked).

How to upload images and other files

  1. Edit a page, and add a link of the form

    [[mypic.jpg:pic]]

    or

    [[mymovie.ogg:video]]

    or

    [[mysound.wav:audio]]

    or

    [[myfile.pdf:file]]

    Note that the filename entered here will be the filename of the uploaded file on your wiki. It need not be the same as the name of the file on your computer.

  2. Save the page, and click on the resulting link.

  3. This will bring up a file upload dialogue. Choose the file to upload, and enter a brief description.

    • For images, this description will be used as the default alt-text of the image.

    • For files, it will be used as a tooltip. It also serves as the default link text, if you don’t specify alternative link text, as below.

    • For video and audio, this will be the fallback text seen by browsers that don’t support the HTML5 <video> or <audio> elements1.

  4. Once the file is uploaded, the image, video or file link should magically appear on your page. If it doesn’t, go back and re-edit the page.

If you want to specify alternative alt-text (or link text), you can use

 [[mypic.jpg|alt text:pic]]

or

 [[myfile.pdf|link text:file]]

It’s also possible to use Markdown-style links to refer to the uploaded files and images. An uploaded image can now be displayed as

   ![alt text](/mywiki/files/mypic.jpg)

An uploaded file can be linked to as

   [link text](/mywiki/files/myfile.pdf)

How to draw commutative diagrams and pictures

The itex syntax accepted by the Azimuth Wiki doesn’t understand the syntax of any diagram-drawing package akin to xypic or tikz. (Many of us would love to improve matters; see the forum, and chime in if you have any suggestions.) At present there are basically three ways to make diagrams: hack it together with arrays, include an image file, or include SVG.

  1. Use arrays or matrices. For example,

    $$
    \begin{matrix}
      (f/g)& \to & A \\
      \downarrow&\underset{\alpha}{\swarr}&\, \downarrow f\\
      B &\underset{g}{\to} & C
    \end{matrix}
    $$

    produces

    (f/g) A α f B g C \begin{matrix} (f/g)& \to & A \\ \downarrow&\underset{\alpha}{\swarr}&\, \downarrow f\\ B &\underset{g}{\to} & C \end{matrix}

    In many cases, you want to tweak the alignments (say, of vertical arrows), using \mathrlap{} or \mathllap{}:

    B A 1 A σ A t α P(B) A χ σ A P(1) A \begin{matrix} B^{\mathrlap{A}} & \longrightarrow & 1^{\mathrlap{A}} \\ \mathllap{\scriptsize{\sigma^A}}\downarrow & & \downarrow\mathrlap{\scriptsize{t^\alpha}} \\ P(B)^{\mathrlap{A}} & \underset{\chi_\sigma^A}{\longrightarrow} & P(1)^{\mathrlap{A}} \end{matrix}

    is produced by

     $$
     \begin{matrix}
     B^{\mathrlap{A}} & \longrightarrow & 1^{\mathrlap{A}} \\
     \mathllap{\scriptsize{\sigma^A}}\downarrow & & \downarrow\mathrlap{\scriptsize{t^\alpha}} \\
     P(B)^{\mathrlap{A}} & \underset{\chi_\sigma^A}{\longrightarrow} & P(1)^{\mathrlap{A}}
     \end{matrix}
     $$
  2. Include an image file: This is the quick-and-dirty method. To create the image file, either use a program like textogif to create the image from a TeX file locally, or use a web service like codecogs. Then follow the instructions in the previous section to upload the file.

  3. Include SVG: This is arguably a “better” method, since unlike an image (and like MathML) SVG can be scaled with the text, and (in theory) edited by other users without recreating the entire diagram. There are various methods for producing SVG. You can use a vector graphics program that produces SVG output (anyone have a good one to suggest?). You can also just copy the SVG from another page and modify it by hand; some pages currently containing SVG diagrams are monoidal category?, oriental? and comma object?. Once you have some SVG, you can modify it by hand to put in the itex math; use the SVG <foreignObject> tag with a $...$ inside it. You need to put markdown="1" on the <foreignObject> tag, or else on a <g> tag containing it.

    Once you have the SVG, you can include it on a page as described here. Since raw SVG is a bit ugly, you may want to put the SVG on a “subpage” by itself (with a name like pagename > imagename) which is included from the main page (see above for the syntax to include other pages).

    You can also use the SVG-editor to create and edit SVGs right here on the Azimuth Wiki. For more details see this entry below.

  4. Use the CodeCogs-server to produce xypic-coded diagrams.

    For that, code a diagram in xypic as usual. Then write the code all in one line without any spaces and in addition replace all appearances of the symbol “&” with “%26”.

    Then add the line

     <img src="http://latex.codecogs.com/gif.latex?YOUR-CODE-GOES-HERE" />

    in the Azimuth Wiki page where the diagram should appear. This will make some server somewhere on this planet produce an image displaying the desired diagram.

    For instance

     <img src="http://latex.codecogs.com/gif.latex?\xymatrix{(f/g)\ar[r]\ar[d]%26A\ar[d]^f\ar[dl]^\alpha\\B\ar[r]_g%26C}" />

    produces

How to fiddle with the CSS (i.e. create query boxes, etc.) on your personal web

Currently nobody has a ‘personal web’ on the Azimuth Wiki, so this section is of purely theoretical interest. As changes even to personal webs require the system password, to make such changes you need to ask a lab elf with sufficient priveleges to do this for you. The best method of doing this is to post a request at the n-forum.

However, you do not need any password to see the stylesheet tweaks on the various webs, so if you see a feature that you would like on one of the other webs (including the main one), then go to the “Edit Web” link at the bottom of that web's HomePage to view the ‘Stylesheet tweaks >>’.

How to use the SVG editor

There is now a WYSIWYG SVG-editor embedded within Instiki (the software running the Azimuth Wiki). The homepage for this editor is here. The Instiki implementation is not feature-complete, yet. In particular, it should be possible to embed itex equations, but those don’t show up in the editor (currently).

Quick Start

  1. Click “Edit page” on a page in which you wish to insert an SVG diagram.
  2. Click in the edit box where you want the diagram to go.
  3. In the list on the right-hand side above the links to the formatting tips is a button labelled “Create SVG graphic”. Click on this. Note: if you forget to do step 2, you won’t be able to click on this button.
  4. The SVG-editor will now launch in a new window. Create your SVG.
  5. When you are done, select “Save SVG” from the file menu. The SVG code will now appear in the edit box of the page.
  6. To edit an existing SVG, select the text between (and including) the <svg> and </svg> tags (but don’t include any whitespace before or afterwards). The “Create SVG” button changes to “Edit existing SVG graphic”.
<!-- Created with SVG-edit - http://svg-edit.googlecode.com/ --> Layer 1 Y × Z Y\, \times\, Z Z Z Y Y X X

Hints and Tips

  1. The editor does not present all options straight away. For example, to get an arrow, you first need to draw a straight line. Then select that straight line (using the selection tool (denoted by an arrow) at the top of the left-hand menu) and a new list of options will appear. One of them is the choice of arrow type.

  2. To get a curved arrow, you use another of the options — the one to turn the line into a ‘path’. After turning the line into a path, double-click on it. This brings up the path options, which include whether the path should be ‘straight’ or ‘curved’. Curved paths are cubic Bézier curves and can also have arrowheads.

  3. You can clone an existing element (an arrow, say), using the rubber-stamp tool.

  4. To get rid of any extraneous whitespace around the picture, go to the “Main Menu” (the funny looking button top left) and select “Document Properties”. There you can set the size of the SVG, including “fit to content”. Only do this once the SVG is finished.

Technical

Software required to use the Azimuth Wiki

The Azimuth Wiki displays mathematical symbols using MathML. Displaying MathML requires support from your web browser. The browser with the best support for MathML is Firefox, especially if you install the STIX fonts. Firefox is a great browser in many other ways too, so if you aren’t using it, why not give it a try?

Recent versions of Opera also apparently support MathML, but as a blog post on Jacques Distler’s Musings points out, this may not work properly. For InternetExplorer, one needs to install the MathPlayer plugin. Download is quick and easy and free, but installation may require Administrator privileges on your computer. Other browsers such as Safari and Chrome seemingly do not support MathML at present.

How to search the Azimuth Wiki & Azimuth Forum from Firefox

(This is specific to Firefox and its clones.)

Here are some search plugins for firefox that will let you search the Azimuth from the firefox search bar.

It would be nice if these had different icons. To use one or more of these, drop them in the ‘searchplugins’ directory of your firefox profile.

Dealing with vandalism

Finally, an unfortunate reality is that sometimes malicious changes get made (often by unregistered users who show up as “Anonymous Coward”). If you happen to spot (and fix) such a change, please go here and post a comment on the Azimuth Forum in the category “Spam” to mention it. This will ensure that it gets seen by the right people!

How to edit Azimuth Wiki pages in your favorite text editor

(This is specific to Firefox and its clones.)

One way to do this is to install this Firefox extension or another one like it.

If your favorite editor is Emacs with AucTeX, you may find the following snippet useful to put in your .emacs file:

(add-to-list 'auto-mode-alist '("/\\(www.\\)?ncatlab.org" . latex-mode))
(add-to-list 'auto-mode-alist '("/golem.ph.utexas.edu" . latex-mode))
(defun nlab-latex-fixes ()
  (when (or (string-match "/\\(www.\\)?ncatlab.org" buffer-file-name)
            (string-match "/golem.ph.utexas.edu" buffer-file-name))
  (longlines-mode t)
  (set (make-local-variable 'TeX-open-quote) "\"")
  (set (make-local-variable 'TeX-close-quote) "\"")))
(add-hook 'LaTeX-mode-hook 'nlab-latex-fixes)

This will tell Emacs to automatically edit nLab pages (and nCafe comments as well, for good measure) in LaTeX mode, with long lines wrapped using soft returns, and ordinary double-quotes rather than LaTeX ones.

How to print a page from the Azimuth Prject

If you just print it directly, the logo will become a huge blob that takes up the entire first page. We can and should fix this, but we haven't. So for now, use the ‘Print’ link at the bottom of the page. As a shortcut in most browsers on most operating systems, hit Alt-Shift-P while the focus is in the page to go to the printable page.

How to customize the Azimuth Wiki

(This is specific to Firefox and its clones.)

You may wish to customize the font scheme (both for math or text) on the nLab, as well as tweak things such as the small edit box for comments. Try using the Stylish add-on if you are using Firefox; Stylish is a plug-in for firefox enabling you to customize websites; it is available here.

Currently, the following stylish themes are available:

  • nLab Stylish theme by Bruce Bartlett. This nLab theme changes the fonts on the nLab to a serif-style, and makes the edit box much bigger for an overall more pleasant experience!
  • nLab – nCafe style by Daniel Schäppi?. This is based on Bruce Bartlett’s theme but changes the overall colour scheme somewhat to something a little more like the n-Cafe.

How to Download a Local Copy of the Azimuth Wiki

The inbuilt export features of the Azimuth Wiki have been switched off. However, it is still possible to get a local version of the n-Lab. This is a static version in that you cannot edit pages, but is complete and all the links correctly point to the pages on the local version.

One way to do this on a Unix-based system (Linux, MacOSX, BSD), is to use the wget command. The command is:

wget --output-document=- http://www.azimuthproject.org/nlab/list \
 | perl -lne '/<div id="allPages"/ and $print = 1;
              /<div id="wantedPages"/ and exit;
              /href="([^"]*)"/ and $print and print "http://www.azimuthproject.org$1";' \
 | wget -i - -kKEpN

(I haven’t tried this so I don’t know if it actually works!)

If you are fortunate enough to be using the Z-shell then you can type it exactly as written. Other shells may complain at the line-breaks in the perl code (they should be alright with the backslashed line-breaks). If so, simply type it all as one line.

One huge advantage of this script over the inbuilt export is that if you run it from the same place each time, it will only download modified pages. That saves a lot of bandwidth and time.

The following is an explanation of how it works. The first step is to get a list of all the pages, we do this by downloading the All pages page and extracting a list of the pages (via a perl script). We feed this back into wget as a list of pages to get (using the -i option). For each downloaded page we ensure that we have the required extras to display it correctly (-p option), we convert the links so that they work correctly: links to downloaded files point to downloaded files, links to non-downloaded files point to non-downloaded files (-k option), we use time-stamping to only get new pages (-N), but because we’re doing a little post-processing we need to keep the original files for time-stamping to work correctly (-K). Files are also converted to html extension (-E) since no matter how they were generated, they are now boring html (well, okay, xhtml+mathml+svg) files.

If anyone can post instructions for other operating systems, or other programs (such as curl) then please do so.

Other Sources of Information

Instiki HowTo

For general information and help with Instiki, see the Instiki wiki.

Here are some useful specifics:

Math typesetting commands

Here’s a survey of available math typesetting commands:

References

This just illustrates the ability to click on a reference and jump straight to the bibliography:

category: meta


  1. Video, in Ogg/Theora format, is supported natively by Firefox and Opera. Safari users need to download an Ogg/Theora Component for Quicktime (available for Mac and Windows). Firefox supports audio in Ogg/Vorbis and WAV formats. Safari (with the above Component installed) supports those, plus several other audio formats supported by Quicktime.