Difference between revisions of "FND-Wiki editing"

From "A B C"
Jump to navigation Jump to search
m
m
Line 184: Line 184:
 
*0.1 First stub
 
*0.1 First stub
 
</div>
 
</div>
−
 
−
{{CC-BY}}
 
  
 
[[Category:ABC-units]]
 
[[Category:ABC-units]]

Revision as of 17:28, 12 September 2021

Wiki editing

(Wiki editing, namespaces; user page setup; copyright, a Course Journal stub page, and an insights! stub page)


 


Abstract:

This should be the first learning unit you work with, since your Course Journal will be kept on a Wiki, as well as all other deliverables. This unit includes an introduction to authoring Wikitext and the structure of Wikis, in particular how different pages live in separate "Namespaces". The unit also covers the standard markup conventions - "Wikitext markup" - the same conventions that are used on Wikipedia - as well as some extensions that are specific to our Course- and Student Wiki. We also discuss page categories that help keep a Wiki organized, licensing under a Creative Commons Attribution license, and how to add licenses and other page components through template codes.

Objectives:

  • Provide an introduction to Wiki principles and Wikitext markup.
  • Create first pages on your own on the Student Wiki.
  • Learn about copyright, why we use Creative Commons licenses for the Student Wiki and how to place a license tag.

Outcomes:

  • You are competent with basic Wiki markup and the extensions on this Wiki.
  • You can create pages and add them to categories while taking care to create them into your own user space.
  • You have created your own user page on the Student Wiki and added contents.
  • You have created page stubs for a Course Journal and an insights! page.

Deliverables:

  • Specified as "Tasks": There are no general deliverables for this unit; specific deliverables are described in the "Task" sections.


    •  



     



     


    Evaluation

    Evaluation: NA

    This unit is not evaluated for course marks.

    Contents

    Collaboration is a common theme for modern lab work and a Wiki is a great way to share and seamlessly update information in groups - or just for yourself. Probably the most sophisticated Wiki software is MediaWiki, a set of PHP scripts that is under continuous development by the Wikimedia foundation; it is the same software that runs Wikipedia. This is open source, free software that is easy to install, is well documented and requires very little resources other than a machine that runs a MySQL database server and an Apache Webserver. Numerous extensions exist (and extensions are not hard to write); they enhance the already rich functionality. But let's start with small steps. You will receive a user account on the Student Wiki, and I have configured that Wiki so that

    • only logged in users can view the pages; but ...
    • all logged in users can create and edit (most) pages.

    This means you could edit pages that don't "belong" to you. Respect the "House Rules" and don't edit others' things without permission, even if you can think of a particularly witty comment or hilarious prank. If you want to comment on a page: every page has an associated "Discussion" page that you can freely edit. Remember to "sign your name" to discussion entries.


     

    Task:

    • Access the Student Wiki;
    • log in and navigate to your user page. (Your user page is linked to your name that appears at the top of every Wikipage once you are logged in.) Create / edit the page, try out and experiment with the Wikitext syntax that this unit covers as you read about the different elements.
    • Work through the contents below.


     


    For more extensive formatting help see: http://meta.wikimedia.org/wiki/Help:Editing
    For Math markup see: http://meta.wikimedia.org/wiki/Help:Formula


     

    The Wiki concept

    Wiki sites are collections of Web pages that allow you to view, edit and create pages from your browser, there is no need for special technology and basic editing is simple and intuitive with "Wikitext markup".

    The basic workflow of Wikis is straightforward:

    • Register an account and browse the site.
    • Whenever you find something that you can improve, edit it.
    • Whenever you find something that you would like to comment on, click on the "discussion" tab and share your views.
    • If you are interested in what becomes of your edits or the discussion, click on the "watch" tab, and the page will be added to a list of bookmarks to pages you are "watching". (You can even generate an RSS feed for recent changes or new pages).

    No e-mail, no obligations. Do what you like, when you like, what you can.

    Editing on the Course Wiki is only enabled for instructors. However you can freely edit all pages on the Student Wiki, once you have an account.


     


     

    Editing basics

    Start editing
    To start editing a Wiki page, click on the "Edit" link at one of its edges. This will bring you to the edit page: a page with a text box containing the wikitext: the editable source code from which the server produces the webpage.


    Preview before saving
    When you have finished, press Show preview to see how your changes will look. Repeat the edit/preview process until you are satisfied, then click Save and your changes will be immediately applied to the article and accessible on the Web. They will also be stored in the main database for as long as the Wiki exists. Thus it is always possible to get back earlier versions of pages - back to the very first edit.


    Basic text formatting

    Here are some examples of the markup of Wikitext. It is not the same as HTML markup, however some HTML markup will work. In particular, the Wiki applies styles through CSS technology (Cascading Style Sheets) and thus HTML tags can be used to apply consistent styles to individual page elements. Javascript won't work.

    What it looks like What you type

    You can emphasize text by putting two apostrophes on each side. Three apostrophes will emphasize it strongly. Five apostrophes is even stronger. 

    You can ''emphasize text'' by putting two
apostrophes on each side. Three apostrophes
will emphasize it '''strongly'''. Five
apostrophes is '''''even stronger'''''.

    A single newline has no effect on the layout.

    But an empty line starts a new paragraph. 

    A single newline
has no effect
on the layout.

But an empty line
starts a new paragraph.

    You can break lines
    without starting a new paragraph.

    		 
    You can break lines<br>
without starting a new paragraph.<br>

    You can format text in a monospace font with a dashed box around it either by marking it with the HTML <pre> tag, or by putting a blank space at the beginning of a line. 

    Example.

    (This may not be very useful beyond the types of examples we show here, but it is a frequent source of confusion, when you find your text marked up this way by accident) 

    You can format text in a monospace
font with a dashed box around it
either by marking it with the HTML
<pre> tag, or by putting a blank
space at the beginning of a line.

 Example.

(This may not be very useful beyond the
types of examples we show here, but
it is a frequent source of confusion, when
you find your text marked up this way by
accident)

    Other special characters at the beginning of a line include:

    • bulleted list
    1. numbered list
    term
    and definition
    		 
    Other special characters at the beginning
of a line include:

* bulleted list

# numbered list

; term
: and definition

    You should "sign" your comments on discussion pages:

    Three tildes gives your user name - Boris (talk)
    Four tildes: user name plus date/time - Boris (talk) 22:18, 27 December 2012 (EST)
    Five tildes: date/time alone - 22:18, 27 December 2012 (EST)
    		 
    You should "sign" your comments on discusion pages:
: Three tildes gives your user name - ~~~
: Four tildes: user name plus date/time - ~~~~
: Five tildes: date/time alone - ~~~~~

    You can use normal HTML character codes for special characters such as > < & ° Å Ä ü →
    ... but modern browsers will handle Unicode well enough: > < & ° Å → 烦死了！ (¬A)⊕A 

    You can use normal HTML character codes for special characters such as &gt; &lt; &amp; &deg; &Aring; &Auml; &uuml; &rarr;
... but modern browsers will handle Unicode well enough: > < & ° Å → 烦死了！ (¬A)⊕A

    You can use HTML tags, too, if you want. Some useful ways to use HTML:

    Put text in a typewriter font. The same font is generally used for computer code.

    Strike out or underline text, write in small caps, highlight, or color for emphasis.

    Superscripts and subscripts: x2, x2

    Invisible comments that only appear while editing the page. 

    You can use <b>HTML tags</b>, too, if you
want. Some useful ways to use HTML:

Put text in a <tt>typewriter font</tt>.
The same font is generally used for
<code>computer code</code>.

<strike>Strike out</strike> or <u>underline</u> text, write 
<span style="font-variant:small-caps"> in small caps</span>, 
<span style="background-color: #FFFFAA;">highlight</span>, or
<span style="color: #DD0000;"> color</span> for emphasis.

Superscripts and subscripts:
x<sup>2</sup>, x<sub>2</sub>

Invisible comments that only appear
while editing the page.
<!-- Note to editors: Be kind! -->

    For a list of HTML tags that are allowed, see HTML in wikitext. I tend to use Wiki-markup when I'm in a hurry, but use the HTML tag whenever I can't remember a Wiki-tag. It really doesn't make a difference.

    However: I never use Wiki-table markup. I find it less intuitive than HTML markup, more difficult to debug, and there's really no point in remembering both types of markup given that one really needs to be comfortable with HTML tables anyway.


     

    Links

    You will often want to make clickable links to other pages.

    What it looks like What you type

    Here's a link to a page named Sandbox. You can even say Sandboxes and the link will show up right.

    You can put formatting around a link. Example: Sandbox. 

    Here's a link to a page named [[Sandbox]].
You can even say [[Sandbox]]es
and the link will show up right.

You can put formatting around a link.
Example: ''[[Sandbox]]''.

    You can link to an arbitrary piece of text with a piped link. Put the link target first, then the pipe character "|", then the link text - as in this example. 

    You can link an arbitrary piece of text
with a ''piped link''. Put the link
target first, then the pipe character "|", then
the link text - as in [[Sandbox| this example]].

    You can make an external link to a Web page just by typing an URL, e.g. http://igem.org

    Or you can link arbitrary text: iGEM. (Note: No "|" for external links, URL and text are separated by a blank, and only single square brackets!)

    Or you can generate a footnote-like link: [1]. 

    You can make an external link to a Web page
just by typing an URL, e.g. http://igem.org

Or you can link arbitrary text:
[http://igem.org iGEM]. 
(Note: No "|" for '''external''' links,
URL and text are separated by a blank,
and only single square brackets!)

Or you can generate a footnote-like link:
[http://igem.org].


    Note: remember:

    • internal links (using [[...]] tags to link to pages on this Wiki) are separated from linked text with a pipe character: [[URL|text]].
    • External links (using [...] tags to link to pages elsewhere on the Internet) are separated from linked text with a space character: [URL text].


     

    Special syntax

    Two special syntax items need to be mentioned: "templates" and "magic words":

    Templates
    Templates are pieces of Wikitext that are substituted where a code that links to them has been placed into a page. For example, if you enter {{Lorem}} on a page, the "Lorem ipsum dolor sit amet ..." placeholder text is inserted in place of that code. Wikis make extensive use of templates.
    Magic words
    some reserved "magic"-words are replaced with dynamically created contents when the page is rendered. For example __TOC__ forces placing a Table Of Contents at the position of this token rather than its default position, while __NOTOC__ suppresses creation of a Table Of Contents on a page.


     

    Creating a new page

    To create a new page simply insert a link to a Wiki page, which has a page name that does not exist yet. The link will appear in red (except if you inadvertently used the name of a page that already exists), and the new page will be created when you click on the link. Page names can be long and contain blank spaces. Internally, all blank spaces are converted to underscore characters, but you can use the page name without underscores in links; the Wiki software translates this for you.


     

    Namespaces

    The Wiki maintains some pages in special collections, in so called "namespaces". This is useful, because the behaviour of the software can be customized for different namespaces: for example you may be allowed to edit in the main- and the user- namespace, but not in the MediaWiki: namespace, where pages are held that affect the gears and wires of the Wiki. Page names without a prefix live in the main space. Some commonly used prefixes are:

    • User: - personal pages for user with an account on the Wiki;
    • Talk: - discussion pages for comments on pages, accessible via the "Discussion" tab;
    • Help: - this page for example;
    • Template: - pages with reusable text.
    • Special: - pages that implement special functionality (like login, user lists, or lists of recently changed pages);
    • Category: - an index of pages that have been given a common tag. This is a convenient way to access pages that are in some way related;


     

    Categories

    Once your page has been edited, you can associate it with one or more categories. For example, add the appropriate category tag by typing [[Category:BCH441_2020]]. The page is then automatically linked from a page that collects all pages with that category tag. I would prefer that you do not create new categories; ask me if you feel a need for it.


     

    Creating a new section or subsection on a page

    To create a section or subsection, simply insert a section header into an existing section. Header levels are defined by the number of "=" characters before and after the header text. Click on an edit link of this page to see example code. Once a page has more than two headings, the Wiki automatically creates a table of contents. You can adjust the position of the table of contents by typing the "magic word" __TOC__somewhere on your page (Note: double underscore), you can also suppress having a table of contents created with__NOTOC__.


     

    Edit conflicts

    If someone else makes an edit while you are making yours, the result is an edit conflict. Many conflicts can be automatically resolved by the Wiki. If it can't be resolved, however, you will need to resolve it yourself. The Wiki gives you two text boxes, where the top one is the other person's edit and the bottom one is your edit. Merge your edits into the top edit box, which is the only one that will be saved.


     

    Reverting pages to a previous state

    Sometimes a page needs to be reverted to a previous state. Access the page through a link to the Recent Changes special page: Special:Recentchanges. Find the page you need to revert, click on the hist link, click on the version you need and verify that it is the correct one. Then click on the edit tab at the top and Save page. A new version of the page is then created with the old text. Note that this does not actually overwrite anything - all edits are archived in the database.


     

    Special markup on this Wiki

    Here are some special templates and extensions installed on this Wiki:


    Vertical space

    The template code {{Vspace}} will insert a two-line high space to help structuring text.


    References and footnotes

    Enclosing text in <ref> ... <\ref> tags will create a footnote reference and display the text wherever you place a <references /> tag on the page.[1] The reference will display as hover-text, so you can keep your references organized in one section of the page, but your in-text citations will show you the contents.

    Syntax highlight

    The GeSHI syntax highlighter extension is installed on this Wiki but it was recently broken by the MediaWiki developers.

    Type: <source lang="R"> for (i in 1:5) { print(i^2) } # 1 4 9 16 25 </source>

    ... to get: 

    for (i in 1:5) {
    print(i^2)
} # 1  4  9  16  25

    Note: no highlighting, and the page is flagged as having syntax highlighting errors.

    Pubmed Articles and abstracts

    {{#pmid:15289071}}

    This inserts the article information in a <div>, formatted by Template:Pubmed.
    Steipe (2004) Consensus-based engineering of protein stability: from intrabodies to thermostable enzymes. Meth Enzymol 388:176-86. (pmid: 15289071)

    [ PubMed ] [ DOI ]


    {{#pmid: 15289071 |Steipe2004}}

    This formats the pubmed parser output for the Cite extension; A footnote mark will be inserted here[2] and the actual reference will appear beneath the <references /> section of the page. This too will be shown as hover-text.

    Math markup

    <math>H = - \sum_{i=0}^n p_i \log_{2} p_i</math>


    Failed to parse (MathML with SVG or PNG fallback (recommended for modern browsers and accessibility tools): Invalid response ("Math extension cannot connect to Restbase.") from server "https://wikimedia.org/api/rest_v1/":): {\displaystyle H = - \sum_{i=0}^n p_i \log_{2} p_i}

    see: http://meta.wikimedia.org/wiki/Help:Formula


    ToDo items

    Type: 

    <div class="ToDo">
ToDo:
* This ...
* and that.
</div>

    ... to get:

    ToDo:

    • This ...
    • and that.


    Notes

    Type: 

    <div class="note">
Note: take special care to ...

</div>

    ... to get:

    Note: take special care to ...


    Linking text to Wikipedia

    ... using the {{WP|...}} template.

    If the linked text is the same as the Wikipedia page titke, simply type it:
    {{WP|Mutual information}}
    Mutual information


     

    If the linked text is different, use the "|" pipe character to separate page-name and text:

    {{WP|Mutual information|'''WP article on Mutual Information'''}}
    WP article on Mutual Information


     

    Collapsible elements

    See: Manual: Collapsible elements 

    <div class="mw-collapsible mw-collapsed" data-expandtext="Expand" data-collapsetext="Collapse" style="width:50%; ">
Visible text  ...
<div class="mw-collapsible-content" style="padding:10px;">
* Collapsed text 1
* Collapsed text 2
* Collapsed text 3
</div>
</div>


    Example:

    The Road Not Taken    Robert Frost

    Two roads diverged in a yellow wood,
    And sorry I could not travel both
    And be one traveler, long I stood
    And looked down one as far as I could
    To where it bent in the undergrowth;
     
    Then took the other, as just as fair,
    And having perhaps the better claim
    Because it was grassy and wanted wear,
    Though as for that the passing there
    Had worn them really about the same,
     
    And both that morning equally lay
    In leaves no step had trodden black.
    Oh, I marked the first for another day!
    Yet knowing how way leads on to way
    I doubted if I should ever come back.
     
    I shall be telling this with a sigh
    Somewhere ages and ages hence:
    Two roads diverged in a wood, and I,
    I took the one less traveled by,
    And that has made all the difference.


    Sample reference section

    1. ↑ This is what the link looks like - and as you can see if you hover over it, the reference gets displayed as hover-text.
    2. ↑
      Steipe (2004) Consensus-based engineering of protein stability: from intrabodies to thermostable enzymes. Meth Enzymol 388:176-86. (pmid: 15289071)

      [ PubMed ] [ DOI ]



     

    The "User space" and its "subpages"

    The User: namespace on the Student Wiki is especially important.

    Namespaces allow us to partition a Wiki into logical sections. The most important sections are the Main: space - for general pages, and the User:-space, for pages that are associated with specific users, like you, yourself. This is important when we need to create similar but unique pages, for assignments and such.

    For example, every student will create a journal page, but page titles on the Wiki must be unique. Thus there can be only one [[Journal]] page on the Wiki. The obvious solution is to keep your "own" pages in the User: namespace, and create them as subpages of everyone's User page. The page name of your user page is [[User:<your-login-name>]]; subpages are created with a backslash, and therefore your Course Journal page should be [[User:<your-login-name>/Journal]].

    Please do not create pages in the "Main space" of the Student Wiki! (I will delete such pages.) Do not omit the User:<your-login-name>/ part of the page name.


     

    Copyright

    Over the last decades, the paradigm under which we create value in science has profoundly changed. Years ago we placed numerous restrictions on the use of our insights, tried to keep control data, and thought in terms of intellectual property. Today, we think about mindshare. We strive to make our work maximally useful to others, and to document how we are creating this utility. This does not mean that we are simply putting everything into the public domain: certainly, people should use our ideas, but we must receive credit - acknowledgement is the currency for grant- and scholarship applications and such, which enables our future work. The right tool for this is copyright.

    Everything we write and create automatically falls under our copyright, there is no special copyright tag required. To have our material reused, we can either relinquish our copyright or grant a license to reuse. Material that is created in coursework will ideally be useful elsewhere, but it is only useful if its use is permitted and regulated.

    Wikis are tools for collaboration, and Wikipedia generally applies a site-wise license to all material. In our work we take a similar approach, but we apply licenses more specifically[1]. All material submitted for credit, including code, documentation, essays, manuals, images, lab journal entries, insights! pages etc. must be licensed with an appropriate open-source license. This is a strict requirement for the course. For code this is the MIT software license, for everything else this is the Creative Commons Attribution 4.0 International License. The MIT license for code guarantees that there are no restrictions on re-use other than fair and visible attribution of the authors' work. The CC license guarantees proper attribution of authorship but allows free use otherwise. Together, these licenses allow the material to be used, refactored, updated and republished and thus (hopefully) give it a fertile future life.

    In order to keep copyright and licenses consistent throughout the site, we use a template tag - simply insert it at the bottom of a page:

    Entering the template code ...
    {{CC-BY}}
    creates the copyright message ...

    CreativeCommonsBy.png This copyrighted material is licensed under a Creative Commons Attribution 4.0 International License. Follow the link to learn more.


     

    Task:

    • Practice basic editing syntax by putting contents on your User Page:
      • enter your name,
      • your major(s), specialist program, year of study - or a link to your lab and your thesis theme if you are a graduate student;
      • enter your email address. I use this information a lot when I need to contact students, so make sure it is correct and current.
      • Add a category tag to your User page. The Wikitext is [[Category:BCH441_2020]]. PLace this at the bottom of the page. All pages with this tag are accessible via the link in the sidebar.
      • Add a copyright template to the bottom of your user page by putting a {{CC-BY}} tag on its bottom.

    Feel free to look at my User Page (or others') for code examples: clicking on the edit link of any page will show you the source text. How do you find my User Page? Good question ...

    • Create a subpage to your User Page; call it "Journal". Note: the link MUST be in your "User space". If you don't add the prefix User:yourname/... before your page name, the new page will end up in the main "namespace". I'll then have to delete it. That's not good. Make sure you know what you are doing, for example by looking at the code on my User Page, asking someone who knows, or asking on the mailing list.
    • Put some placeholder text on your journal page, you will fill it in when you work through the Journal unit.
    • Similarly, create an "insights!" page on a subpage to your User Page and add some placeholder text. That will be expanded when you work through the insights! unit.
    • Play around some more. Feel free to ask how to go about achieving a particular effect that you may have seen elsewhere.

    Self-evaluation

    You should be familiar with the following:

    • How to Login to the Student Wiki and access your user page;
    • viewing a page's history;
    • basic text formatting and Wiki markup;
    • "signing" your name;
    • creating internal and external links;
    • creating section headers on a page on multiple levels;
    • reverting a changed page to an earlier version;
    • creating a new page (as a subpage of an existing page);
    • the concept of namespaces - especially the default ("main") and User: namespace;
    • the concept of categories and how to add a page to a category;
    • copyright on the Student Wiki, and how to insert a license note.

    Notes

    1. ↑ Note that additional rules for collaboration in the context of coursework derive from the rules for academic integrity and plagiarism. If some text is not copyrighted, this does not mean you can use it without reference and thus imply it is your own idea. That would be plagiarism.


     


    About ...
     
    Author:

    Boris Steipe <boris.steipe@utoronto.ca>

    Created:

    2017-08-05

    Modified:

    2020-09-08

    Version:

    1.2

    Version history:

    • 1.2 Maintenance updates
    • 1.1 Changed software license from GNU-GPL to MIT
    • 1.0 Completed outcomes/objectives. Added copyright. First live version.
    • 0.2 First contents imported from Help:editing. Added tasks.
    • 0.1 First stub
    Retrieved from "http://steipe.biochemistry.utoronto.ca/abc/index.php?title=FND-Wiki_editing&oldid=11964"