[go: up one dir, main page]

nLab HowTo (Rev #163, changes)

Showing changes from revision #162 to #163: Added | Removed | Changed

This page gives hints for how to edit nLab-pages.

An easy introduction for elementary basics is

The following provides more details. For technical help with special features of Instiki (including peculiarities with itex), HTML and XML, and assorted specifics of the nLab, see also the FAQ.

Contents

Technical

Technical

Software required to use the nnLab

Software required to use the nnLab

The nnLab serves mathematical symbols as MathML. Presently the only browser with native MathML support, and hence immediate rendering of the formulas, is Firefox.

Essentially all other browsers fall back to rendering MathML formulas using the MathJax polyfill. This works, but is slow. On small pages it is fine, on larger pages with many formulas MathJax may take up to several minutes for rendering.

How to search the nLab & nForum from firefox

How to search the nLab & nForum from firefox

(Firefox - and clones - specific)

Here are some search plugins for firefox that will let you search the nLab from the firefox search bar. EDIT: These are old and may not work with recent versions of Firefox. Instead you can use the search engine creator plugin. Someone should update these files to conform to OpenSearch; then they might work with other browsers too.

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.

Alternatively, you can try the add to search bar add-on for Firefox. This will let you right-click in the search box on any page and add it to your search bar. (You can’t duplicate the “goto” and “edit” plugins this way, though.)

If DuckDuckGo is your search engine, you can type “!nl” to search nLab, e.g. “!nl morphism”.

How to edit nLab pages in your favorite text editor

How to edit nLab pages in your favorite text editor

(Firefox - and clones - specific)

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 nLab

How to print a page from the nLab

If you just print it directly, the logo will become a huge blob that takes up the entire first page. I know, 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 nLab

How to customize the nLab

(Firefox - and clones - specific)

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 nLab

How to download a local copy of the nLab

It is possible to download an SQL dump of the nLab database, from which both the nLab and nForum can be reconstructed. Some of us are running cron jobs to do this regularly. The more the merrier: if you are interested, please request that we create a user for you to be able to do this in the nForum, say in this thread.

If you would like instead to download rendered nLab pages for local viewing, let us know as well at the nForum.

Getting Started

Getting Started

How to use a Wiki

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

How to start a new page

You do this in two 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.)

  2. Clicking on the question mark to begin editing the new page. (It will not actually be created until you hit Submit.)

Watch out: the name of a page is case sensitive, so make your link lowercase if it comes at the beginning of a sentence. ([[like this|Like this]].) We loosely agreed to try to follow that and some other naming conventions; see below.

However, this is less of an issue now that we have redirects.

Signing

Signing

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 ‘Anonymous’ (formerly 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.)

Naming conventions

Naming conventions

The following naming conventions for new entries 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.

    • Examples: [[omega-category]] instead of [[$\omega$-category]] or [[∞-category]].
    • Tricks: To produce ‘ω\omega-category’, try $\omega$-[[omega-category|category]]. To produce ‘∞-category’, try [[omega-category|∞-category]]. (The former has proper math-mode formatting, while the latter has proper link scope.) Unfortunately, $\omega$-category does not work. You can also use redirects to make [[∞-category]] produce ‘∞-category’, but only when the page already exists.
    • 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. This also helps with creating automatic redirects (which are found by removing accents on letters).
    • Exception: We tend to use common European letters (such as ‘ö’, more or less the characters in Latin 1) in names, especially of people (such as Kurt Gödel), even though we're not really supposed to.
  • Page titles should be singular nouns.

    • Examples: Use [[category]] instead of [[categories]], [[faithful functor]] instead of [[faithful]], and [[categorification]] instead of [[categorify]] or [[categorified]].
    • Tricks: To produce ‘categories’, try [[category|categories]]. To produce ‘faithful endofunctor’, try [[faithful functor|faithful]] [[endofunctor]]. Again, you can use redirects to make [[categories]] produce ‘categories’, if the page already exists.
    • Reason: We want only one page on a given concept, regardless of variations in grammar.
    • Exception: Recently we have started to have page titles that are complete sentences (without capitalization or punctuation) that state a simple theorem (typically a universal affirmation in the Aristotelian sense) such as compact Hausdorff rings are profinite or derivations of smooth functions are vector fields.
  • Page titles should be uncapitalized, except for words that are always capitalized.

    • Examples: Use [[homotopy theory]] instead of [[Homotopy Theory]], but use [[Lie algebra]].
    • Tricks: To produce ‘Homotopy theory is important!’, try [[homotopy theory|Homotopy theory]] is important!. If you do this a lot, then you can again create a redirect, if the page exists.
    • Reason: We want only one page on a given concept, regardless of variations in grammar.
  • Except as contradicted above, use standard American English spelling conventions.

    • Examples: Use [[center]] instead of [[centre]] and hyphens as shown in the ASCII-only requirement.
    • Tricks: To produce ‘centre’, try [[center|centre]]. Or, again, make a redirect.
    • Reason: Most of this is written by Urs Schreiber, who uses American English spelling.
  • Regardless of the above, pages named after specific categories should use the capitalised singular abbreviated form.

    • Examples: Use [[Set]] instead [[Sets]] and [[Cat]] instead of [[Category]].
    • Tricks: Although things like ‘Disc:SetCat\Disc: \Set \to \Cat’ work best in math mode and even ‘Set\Set’ alone looks most consistent that way (with proper math-mode formatting), you have to make the link ‘Set’ outside of math mode.

How to merge pages

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 ‘ ’ 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 ‘ ’ to the top.
  6. Change the line ‘ ’ 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’). But if they're really at ‘B > history’ on purpose to check the edit history, then that history is there for them.

How to remove a page

How to remove a page

To remove a page, look at category: empty and see which number should be used next, then rename the page to empty ### using that number. Replace the content (including the automatically added redirect) with category: empty.

(To remove the backlog of empty pages, one should also create pages by reversing this process, although it's easy to forget to do that.)

How to organize and write content

How to organize and write content

Page organization

Page organization

We encourage authors to structure pages by sections and subsections as indicated in the

Every page starts out tiny and may not seem to need a structure by subsections. But it will grow and eventually the information it provides may be hard to recognize without some global structure guiding the reader’s attention. After all, the natural evolution of articles makes the nnLab function more like an encyclopedia than a novel. Moreover, even with little material there in the beginning, a structure by subsections helps the collaborative process, as it makes it easer to decide for new authors where to add what.

Definition-, Theorem-, Proof environments

Definition-, Theorem-, Proof environments

You should include actual mathematics in appropriate environements, as familiar from textbooks and research articles in mathematics.

The syntax for this is given at Instiki theorem environments:

A definition should be enclosed in

 +-- {: .num_defn}
 ###### Definition

  (Definition goes here)

 =--

A proposition or theorem should be enclosed in

 +-- {: .num_prop}
 ###### Proposition

  (Proposition goes here)

 =--

or

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

  (Theorem goes here)

 =--

and their proof in

 +-- {: .proof}
 ###### Proof


   (Proof goes here.)

 =--

A corollary in

 +-- {: .num_cor}
 ###### Corollary

  (Corollary goes here)

 =--

and a remark in

 +-- {: .num_remark}
 ###### Remark

  (Remark goes here)

 =--

Apart from ensuring that it is clear to the reader at each stage what your text is meaning to accomplish, this will make the software format your text appropriately (for instance propositions and theorems will be set in italics) and automatically add a numbering.

Beware that you do need to use the labels exactly as given above. It needs to be defn, thm, and cor; neither definition nor theorem nor corollary (nor other abbreviations such as def) will be recognized by the software.

A central point of the nnLab is that information is linked. Little value is added to the world when information is added to an nnLab page if it is not interlinked there with other nnLab entries such as to make sure that users who might look for it will actually eventually find it by following some links.

Therefore you should hyperlink the central keywords in what you write, by enclosing them in square brackets. Ideally, each and every keyword would be hyperlinked, certainly when it occurs first. Don’t assume that the reader has the same background as you have. If you explain something by invoking other technical terms, at least provide links to nnLab entries where these other terms are defined.

Analogously, when you create a new page, make sure that it is linked to from at least one relevant other page. An entry on a new kind of manifold deserves to be linked to from a list of “related entries” at manifold, for instance.

Apart from guiding users to your entry this way, notably this will also help search engines to index the nnLab and make your new entry appear listed when people search for something related.

Mathematical conventions

Mathematical conventions

There is really no such thing as a “global convention on the nnLab” for ambiguous meaning of mathematical terms and symbols. Unlike in a text book by a single or a handful of authors, there is just no way that we can even try to enforce global conventions. Typically each author decides on his or her own.

Therefore the general rule is: whatever you write in some entry, try to make sure that you provide enough context that the relevant conventions are clear. If you find yourself using some notation for the first time on a page and are worrying if readers will read it as intended, be sure to add a parenthetical remark (where we use here the convention that…) or similar.

If you feel that you need to refer to a specific convention repeatedly over several nnLab pages, just create another page that states the convention, and then simply point to that page.

One example of this that we have is the implicit infinity-category theory convention-page.

Special Typesetting Features

Special Typesetting Features

How to make links to subsections of a page

How to make links to subsections of a page

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

 <nowiki>## Heading {#anchorname}</nowiki>

Note that the tag must be placed at the end. Then you can make a link to it using the syntax:

 <nowiki>[[some page#anchorname|link text]]</nowiki>

If the link is to the same page then the page name can be omitted by using the syntax:

 <nowiki>[link text](#anchorname)</nowiki>

Note that a single bracket link with only an anchor doesn’t function correctly when viewing a particular revision or a difference between revisions.

Strangely single bracket link texts allow math expressions while double bracket texts don’t. For example

<nowiki>[$Set^\to$](Sierpinski+topos) vs [[Sierpinski topos|$Set^\to$]] vs [$Set^\to$](https://ncatlab.org/nlab/show/Sierpinski+topos).</nowiki>

produces

Of course, you can link to it from outside the nLab by adding http://ncatlab.org at the beginning of the link.

Note that if you skip the first step, it is still possible to create a link to a subsection, since (at least if the page has a table of contents) 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.

The same type of syntax enables one to link to arbitrary text blocks such as paragraphs or list elements, such as a link to this paragraph itself. Note that these tags must be at the start of the text. In particular, a bibliographic reference can be made by first by creating an anchor:

 * {#xyz} Reference 

which can then be linked to from within the same page by writing

 [link text](#xyz). 

Definition/Proposition/Theorem-numbering

Definition/Proposition/Theorem-numbering

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

 +-- {: .num_defn #definitionname}
 ###### Definition
 ...
 =--


 +-- {: .num_prop #propname}
 ###### Proposition
 ...
 =--


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

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

 [[some page#theoremname|see this theorem]]
 [see this theorem](#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.

Equation numbering

Equation numbering

To make an equation be automatically numbered use angular brackets instead of dollar signs

 \[
   \exp(\pi i) + 1 = 0 
 \]

To refer to this numbered equation, add a label

 \[
   \label{SomeEquation}
   \exp(\pi i) + 1 = 0 
 \]

and then refer to it later in the text by typing

 see equation (eq:SomeEquation) .

Automatic table of contents

Automatic table of contents

Insert the symbols

     * table of contents 
     {: toc}

(including the line break!) at the position where the table of contents is to appear. You may want to label the table of contents by writing

 # Contents #
 * table of contents 
 {: toc}

or (at the top of the page)

 # [page title] #
 * table of contents 
 {: toc}

(which also gives the opportunity to use a more nicely formatted page title if special characters or mathematical formatting are wanted).

The items in the table of contents will be the section headlines marked by

 ## top level headline ##


 ### second level headline ###


 etc.

Instead of “table of contents” after the asterisk, you can write anything you like: this line will not be displayed but is still required to kick in the CSS that makes this possible.

It is 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 have a link inside of a link).

How to cite and record references

How to cite and record references

At the end of each nnLab entry should be a section

  ## References

or sometimes

  ## Literature

which contains a bullet list of relevant references. A standard way to format an entry is this list is the following:

  * {#LastnameAnotherlastnameYear} [[Firstname Lastname]], [[Anotherfirstname Anotherlastname]], _Title_, Journal, volume, year ([arXiv:xxxx.yyyyy](https://arxiv.org/abs/xxxx.yyyyy), [doi:xyz](http://doi.xyz))

which comes out as

Given such an item in the list of references, a standard way to reference it from the main text of the entry is as follows:

  see ([Lastname-Anotherlastname Year, theorem 1.3](#LastnameAnotherlastnameYear))

which comes out at

see (Lastname-Anotherlastname Year, theorem 1.3)

This produces a hyperlink, and in fact such that following it brings up the above bullet item highlighted by a gray box.

How to make comments and ask questions

How to make comments and ask questions

In general, the place to make comments and ask questions is on the n-Forum. Some information about the n-Forum can be found on nlabmeta; just find or create a forum discussion about the page you want to talk about and talk away.

When questions are answered and discussions are resolved at the n-Forum, the conclusion should often be recorded on an nLab page. If it’s about a particular page, then of course put it on that page; if it’s a general question then it could be recorded on this How To or the FAQ. As this is a wiki, you can do this recording yourself when your question is answered.

That said, the wiki software does contain a mechanism for putting questions and comments on a wiki page itself: 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?

In general, this is the wrong way to go about asking a question. When you put a query box on a page, often none of the other contributors will notice it for a long time, so it will take a long time for the question to be answered, and in the meantime it makes the page cluttered and ugly for other readers. However, occasionally it may be appropriate to record a brief question in a query box, if it has already been discussed at the nForum and the conclusion was not satisfactory. In this case a link to the nForum discussion should be included in the query box in preference to any lengthy detail about the question and discussion.

(Before the n-Forum existed, it was much more common to ask questions using query boxes. Some such query boxes still remain undiscovered on various pages, but whenever we find one we generally migrate it to the n-Forum.)

How to make a standout box

How to make a standout box

If you want to make some text stand out (an important theorem, or slogan), you can do it using a standout box. The mechanism is similar to a query box, although the purpose is different: while a query box is for a temporary question and should be removed once that question is resolved, a standout box is a permanent feature of a page that simply emphasizes a small amount of text. To make a standout box, write:

+-- {: .standout}
First quantization is a mystery, but second quantization is a functor. 
=--

which produces

First quantization is a mystery, but second quantization is a functor.

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

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

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 include one page within another

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 [[!include foo]] 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, see here) without mucking up the rest of the page. That is, you put your messy code in bar/foo and then put [[!include bar/foo]] 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 upload files

How to upload files

To upload a file, proceed as follows:

  1. Type

    [[FileName.xyz:file]] 

    into the edit-pane of some entry;

  2. hit “submit”;

  3. in the rendered entry, find a grayish link labeled “FileName.xyz” followed by a question mark;

  4. click on the question mark to open an upload dialogue and follow the instructions there;

    notice that the dialogue field “Description” is asking for the text that will appear hyperlinked to your file. If you put not text here, no link to your file will appear by itself;

  5. complete the dialogue by hitting “upload”;

  6. find in the rendered entry the previously grayish text “FileName.xyz” replaced by the text that you entered into the “Description”-box in the file upload dialogue, and hyperlinked to your file;

  7. due to a bug, if you want that link to persist, you need to make any further edit to the entry (e.g. add a whitespace) and “submit” again.

After this, the file is now sitting at this URL:

  https://ncatlab.org/nlab/files/FileName.xyz 

Hints:

  1. If you uploaded a picture, you will probably want to remove the file upload code

    [[FileName.xyz:file]] 

    (which renders to a link to the file) and instead add lines like

    <div style="float:right;margin:0 20px 10px 20px;">
    <img src="https://ncatlab.org/nlab/files/FileName.xyz" width="300" />
    </div>

    or

    <center>
    <img src="https://ncatlab.org/nlab/files/FileName.xyz" width="300" />
    </center>

    or the like, which make the actual picture show up in the entry.

  2. If you uploaded a pdf (or similar) for a reference, you will probably want to make sure that the “Description” text in the upload dialogue is “pdf” (or similar), so that the code

     A. Name, _A title_, A Journal, AYear ([[FileName.xyz:file]])

    renders to

    “A. Name, A title, A Journal, AYear (pdf)”

    with “pdf” hyperlinked to your file.

  3. There is a size limit for files to upload. The functionality is meant to be used for uploading ingredients of nnLab entries (such as pictures or references) which are not available for linking elsewhere on the web, or not reliably so.

    If you try to abuse the file upload for archiving your personal files, the steering committee will intervene.

How to include SVG figures

How to use redirects

To include an SVG figures within a page, proceed as following:

  1. The nnLab has a built-in SVG editor (see below). Click on the “Create SVG graphic” button to open it. Choose “Save Image” from the SVG-Edit menu when you’re done. This will close the SVG editor and paste the resulting SVG code back into the Editing window.

  2. If you produce the SVG with a standard SVG editor, save it using, if possible, the two options

    1. save as plain SVG
    2. save as optimes SVG
  • You need to include the resulting source code . Uploading the SVG as a file to the nnLab won’t work. So

    1. Go to the page where you want to include the SVG, say titled “SomePage”, and at the point where the figure is to appear insert the code

      ``` +--{: style="text-align:center"} [!include SomePage > figureN]] =-- ```

    2. Then type

      http://ncatlab.org/nlab/show/SomePage > figureN

      into your browser’s address line. The software will ask you to create a page with the title “SomePage > figureN”. Paste the source code of your SVG into this page and hit Submit .

      Go back to SomePage . The SVG figure should now be displayed there.

See for instance the entry comma object for an example.

How to use redirects

See redirects.

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

How to add a floating table of contents

How to add a floating table of contents

Many pages include a “floating table of contents” at the top right-hand side with links to other pages on similar topics. The lists of related pages are separate pages with names such as category theory - contents; if you want to create a new one, look at the syntax of existing ones.

To add a floating TOC to a new page, in such a way that it will be automatically collapsed until moused over, use code such as the following at the top of the page:

+-- {: .rightHandSide}
+-- {: .toc .clickDown tabindex="0"}
### Context
#### Category Theory
+-- {: .hide}
[[!include category theory - contents]]
=--
=--
=--

If you want to include multiple contents pages, you can repeat the four lines from the one starting with #### through the first =-- line.

How to draw commutative diagrams and pictures

How to draw commutative diagrams and pictures

The itex syntax accepted by the nlab 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.

Tikz

  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 A 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^A}} \\ 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}
     \]

    Matrix and array environments also accept certain options. Here is an example using a “\rowlines{solid}” option to hack a sequent derivation (much more nicely than by resorting to \frac commands):

    X×BPAinS X×BAinRel(S) XA×BinRel(S) XP(A×B)inS \array{\arrayopts{\rowlines{solid}} X \times B \to P A\;\;\; in\; \mathbf{S} \\ X \times B \nrightarrow A\;\;\; in\; Rel(\mathbf{S}) \\ X \nrightarrow A \times B\;\;\; in\; Rel(\mathbf{S}) \\ X \to P(A \times B)\;\;\; in \; \mathbf{S} }

    is produced by

    $$
    \array{
    \arrayopts{\rowlines{solid}}
    X \times B \to P A\;\;\; in\; \mathbf{S} \\
    X \times B \nrightarrow A\;\;\; in\; Rel(\mathbf{S}) \\
    X \nrightarrow A \times B\;\;\; in\; Rel(\mathbf{S}) \\
    X \to P(A \times B)\;\;\; in \; \mathbf{S}
    }$$
  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 (warning, codecogs xy-support seems to be broken now) or QuickLatex or presheaf.com. Then follow the instructions here for putting it on the lab.

  3. Include SVG: See here for the general procedure. 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 in the lab. For more details see this entry below.

  4. Use the CodeCogs-server to produce xypic-coded diagrams (WARNING: this seems to be broken now, try a similar service such as presheaf.com).

    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 nnLab 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

As of 2019, one can use tikz or tikzcd exactly as one would in LaTeX. Take a look at the source of this page to see how the code for the figures.

Vertical bars and reversed brackets

Picture:

This \begin{centre} is \begin{tikzpicture} basically \draw working around some missing features of iTeX. Even in real TeX, typing|x|blue, -> (or equivalently (1,0) (1,-1); \end{tikzpicture} \end{centre}\vert x\vert) for |x||x| is not entirely correct; you should either type \mathopen|x\mathclose| or \lvert x\rvert to guarantee proper spacing. This rarely makes any visible difference, although |-| is dramatically wrong. (The same goes for \|, \Vert, \lVert, and \rVert.)

This Commutative is diagram: not just a lesson in the fine points of TeX, however, since iTeX does not support any of these nuances! Furthermore, iTeX renders| (or equivalently \vert) into MathML as an operator (like \mid) rather than as an ordinary symbol (as real TeX does), so that bad spacing comes up much more often. To work around this, you usually need to put braces around the bars, and sometimes you need to put them inside the bars as well. (In any case, it never hurts.)

Much \begin{centre} the \begin{tikzcd} same x applies \ar[r] to & reversed y brackets. \end{tikzcd} In \end{centre} real TeX,[x[ should really be [x\mathclose[; in iTeX, you can write this effectively as {[x[}.

Thus: The only difference to LaTeX is that\usetikzlibrary lines should be put inside the blocks.

  • $|a|$ is fine: |a||a|.
  • $|a| + \|x\|$ has bad spacing: |a|+x|a| + \|x\|.
  • ${|a|} + {\|x\|}$ is fine: |a|+x{|a|} + {\|x\|}.
  • $|-|$ has bad spacing: |||-|.
  • $|{-}|$ is fine: |||{-}|.
  • ${|{-}|} + {\|{-}\|}$ (but nothing simpler) is fine: ||+{|{-}|} + {\|{-}\|}.

Under the hood, this works by running pdflatex and then generating an SVG from the resulting pdf, which is included in the HTML source of the rendered page.

Similarly:

Older workaround for commutative diagrams

  • $]0,2[$ is fine: ]0,2[]0,2[.
  • $]0,2[ - ]1,2[$ has bad spacing: ]0,1[]1,2[]0,1[ - ]1,2[.
  • ${]0,2[} - {]1,2[}$ is fine: ]0,1[]1,2[{]0,1[} - {]1,2[}.
  • $]-1,0[$ has bad spacing: ]1,0[]-1,0[.
  • $]{-1,0}[$ is fine: ]1,0[]{-1,0}[.
  • ${]{-2,0}[} - {]{-1,0}[}$ (but nothing simpler) is fine: ]2,0[]1,0[{]{-2,0}[} - {]{-1,0}[}.

An older workaround is to use use arrays or matrices. For example,

Some of these examples of bad spacing will also be bad in real TeX; but iTeX exaggerates the errors and limits the ways that you can fix them.

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

How to use the SVG editor

produces

There is now a WYSIWYG SVG-editor embedded within Instiki (the software running the nLab). The homepage for this editor is here.

(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}

Quick Start

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

  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”.
B A 1 A σ A t A 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^A}} \\ P(B)^{\mathrlap{A}} & \underset{\chi_\sigma^A}{\longrightarrow} & P(1)^{\mathrlap{A}} \end{matrix}
<!-- Created with SVG-edit - http://svg-edit.googlecode.com/ --> Layer 1 Y × Z Y\, \times\, Z Z Z Y Y X X

is produced by

Hints and Tips

    \[
    \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}
    \]
  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.

Matrix and array environments also accept certain options. Here is an example using a “\rowlines{solid}” option to hack a sequent derivation (much more nicely than by resorting to \frac commands):

Other Sources of Information

X×BPAinS X×BAinRel(S) XA×BinRel(S) XP(A×B)inS \array{\arrayopts{\rowlines{solid}} X \times B \to P A\;\;\; in\; \mathbf{S} \\ X \times B \nrightarrow A\;\;\; in\; Rel(\mathbf{S}) \\ X \nrightarrow A \times B\;\;\; in\; Rel(\mathbf{S}) \\ X \to P(A \times B)\;\;\; in \; \mathbf{S} }

Instiki HowTo

is produced by

   $$
   \array{
   \arrayopts{\rowlines{solid}}
   X \times B \to P A\;\;\; in\; \mathbf{S} \\
   X \times B \nrightarrow A\;\;\; in\; Rel(\mathbf{S}) \\
   X \nrightarrow A \times B\;\;\; in\; Rel(\mathbf{S}) \\
   X \to P(A \times B)\;\;\; in \; \mathbf{S}
   }$$

But use Tikz wherever possible.

Image files

One can upload an image to the nLab as follows.

  1. Add [[some_picture.jpg:pic]] or [[some text that you wish to display|some_picture.jpg|pic]] to the page to which you wish to add the image. Save your edit.

  2. Click on the ? symbol that appears after ‘some_picture.jpg’ or ‘some text that you wish to display’ on the page.

  3. You will be sent to a page where you can upload the image.

Once uploaded, the picture should appear on the page.

Other Sources of Information

Instiki HowTo

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

Here are some useful specifics:

survey of available math typesetting commands

Survey of available math typesetting commands

This is worth perusing carefully; for example, iTeX does not provide a command such as \prescript to generate left subscripts. Instead it contains the more general \multiscripts command to typeset subscripts and superscripts both to the left and right of an expression. For instance, the math mode text \multiscripts{_0^2_1}{R}{_i^j_k} produces

Ri j k 0 2 1 \multiscripts{_0^2_1}{R}{_i^j_k}

category: meta

Revision on January 20, 2019 at 13:37:21 by Richard Williamson See the history of this page for a list of all contributions to it.