NOTE: We are working on migrating this site away from MediaWiki, so editing pages will be disabled for now.
Difference between revisions of "Site Guidelines"
m (Text replace - "</xml>" to "</syntaxhighlight>") |
m (Info about adding references) |
||
Line 66: | Line 66: | ||
− | <nowiki>#REDIRECT [[Page Name to Redirect to]]</nowiki> | + | |
+ | <nowiki>#REDIRECT [[Page Name to Redirect to]]</nowiki> | ||
In our example this would be: | In our example this would be: | ||
− | <nowiki>#REDIRECT [[GBrowse]]</nowiki> | + | |
+ | <nowiki>#REDIRECT [[GBrowse]]</nowiki> | ||
and then save the page. | and then save the page. | ||
Line 155: | Line 157: | ||
Check the thingy.conf file. | Check the thingy.conf file. | ||
| <pre> | | <pre> | ||
− | <nowiki>Check the <tt> | + | |
+ | <nowiki>Check the <tt>thingy.conf</tt> file.</nowiki> </pre> | ||
---- | ---- | ||
Check the <tt>thinigy.conf</tt> file. | Check the <tt>thinigy.conf</tt> file. | ||
Line 199: | Line 202: | ||
| | | | ||
− | <nowiki>~/work/galaxy-dist$ <span class="enter">head tool_conf.xml</span></nowiki> | + | |
+ | <nowiki>~/work/galaxy-dist$ <span class="enter">head tool_conf.xml</span></nowiki> | ||
---- | ---- | ||
~/work/galaxy-dist$ <span class="enter">head tool_conf.xml</span> | ~/work/galaxy-dist$ <span class="enter">head tool_conf.xml</span> | ||
Line 208: | Line 212: | ||
| | | | ||
+ | |||
<nowiki>Edit the configuration file: | <nowiki>Edit the configuration file: | ||
− | gedit thingy.conf</nowiki> | + | gedit thingy.conf</nowiki> |
---- | ---- | ||
Edit the configuration file: | Edit the configuration file: | ||
Line 215: | Line 220: | ||
| | | | ||
+ | |||
<nowiki>Edit the configuration file: | <nowiki>Edit the configuration file: | ||
gedit thingy.conf | gedit thingy.conf | ||
− | {{TextEditorLink|gedit}}</nowiki> | + | {{TextEditorLink|gedit}}</nowiki> |
---- | ---- | ||
Edit the configuration file: | Edit the configuration file: | ||
Line 277: | Line 283: | ||
: These can be negative examples or things were done to the VMware image before the course. | : These can be negative examples or things were done to the VMware image before the course. | ||
| <pre> | | <pre> | ||
+ | |||
<nowiki><div class="dont"> | <nowiki><div class="dont"> | ||
Here's an example of what ''not'' to do: | Here's an example of what ''not'' to do: | ||
cd /; | cd /; | ||
sudo rm -rf * | sudo rm -rf * | ||
− | </div></nowiki> </pre> | + | </div></nowiki> </pre> |
---- | ---- | ||
<div class="dont"> | <div class="dont"> | ||
Line 295: | Line 302: | ||
| | | | ||
+ | |||
<nowiki>Now, to enable this theme, | <nowiki>Now, to enable this theme, | ||
navigate to Administer, Site | navigate to Administer, Site | ||
Building, Themes page and select | Building, Themes page and select | ||
− | the Pixture Reloaded radio button.</nowiki> | + | the Pixture Reloaded radio button.</nowiki> |
---- | ---- | ||
Now, to enable this theme, navigate to Administer, Site Building, Themes page and select the Pixture Reloaded radio button. | Now, to enable this theme, navigate to Administer, Site Building, Themes page and select the Pixture Reloaded radio button. | ||
| | | | ||
+ | |||
<nowiki>Now, to enable this theme, | <nowiki>Now, to enable this theme, | ||
''navigate'' to the '''Administer | ''navigate'' to the '''Administer | ||
&rarr; Site Building &rarr; Themes''' | &rarr; Site Building &rarr; Themes''' | ||
page and ''select'' the | page and ''select'' the | ||
− | '''Pixture Reloaded''' button.</nowiki> | + | '''Pixture Reloaded''' button.</nowiki> |
---- | ---- | ||
Now, to enable this theme, ''navigate'' to the '''Administer → Site Building → Themes''' page and ''select'' the '''Pixture Reloaded''' button. | Now, to enable this theme, ''navigate'' to the '''Administer → Site Building → Themes''' page and ''select'' the '''Pixture Reloaded''' button. | ||
Line 319: | Line 328: | ||
===Google Documents=== | ===Google Documents=== | ||
− | <nowiki>{{#widget:</nowiki>GoogleDocument | + | |
+ | <nowiki>{{#widget:</nowiki> GoogleDocument | ||
|id=<document ID> | |id=<document ID> | ||
|width=<width> | |width=<width> | ||
Line 329: | Line 339: | ||
===Google Presentations=== | ===Google Presentations=== | ||
− | <nowiki>{{#widget:</nowiki>GooglePresentation | + | |
+ | <nowiki>{{#widget:</nowiki> GooglePresentation | ||
|id=<presentation ID> | |id=<presentation ID> | ||
|width=<width> | |width=<width> | ||
Line 341: | Line 352: | ||
===Google Calendars=== | ===Google Calendars=== | ||
− | <nowiki>{{#widget</nowiki>:GoogleCalendar | + | |
+ | <nowiki>{{#widget</nowiki> :GoogleCalendar | ||
|id=usa@holiday.calendar.google.com | |id=usa@holiday.calendar.google.com | ||
|color=B1440E | |color=B1440E | ||
Line 358: | Line 370: | ||
More documentation on the [http://www.mediawiki.org/wiki/Extension:OFlash OFlash MediaWiki page]. | More documentation on the [http://www.mediawiki.org/wiki/Extension:OFlash OFlash MediaWiki page]. | ||
− | + | ==Writing Code== | |
− | The GMOD wiki employs the extension [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi Syntax Highlight GeSHi] to produce code with highlighting. For coloured code, use the <tt><nowiki><</nowiki>syntaxhighlight></tt> tag: | + | The GMOD wiki employs the extension [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi Syntax Highlight GeSHi] to produce code with highlighting. For coloured code, use the <tt> |
+ | <nowiki><</nowiki> syntaxhighlight></tt> tag: | ||
− | <nowiki><</nowiki>syntaxhighlight lang="perl"> | + | |
+ | <nowiki><</nowiki> syntaxhighlight lang="perl"> | ||
#!/usr/bin/perl | #!/usr/bin/perl | ||
my $life = "over"; | my $life = "over"; | ||
Line 368: | Line 382: | ||
<nowiki><</nowiki>/syntaxhighlight> | <nowiki><</nowiki>/syntaxhighlight> | ||
− | + | <syntaxhighlight lang="perl"> | |
#!/usr/bin/perl | #!/usr/bin/perl | ||
my $life = "over"; | my $life = "over"; | ||
die("Goodbye, cruel world!"); | die("Goodbye, cruel world!"); | ||
− | + | </syntaxhighlight> | |
Languages supported include Javascript, Java, Perl, PHP, XML, CSS, and more. Full documentation can be found on the [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi Syntax Highlight GeSHi] MediaWiki page. | Languages supported include Javascript, Java, Perl, PHP, XML, CSS, and more. Full documentation can be found on the [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi Syntax Highlight GeSHi] MediaWiki page. | ||
+ | |||
+ | ==Adding References== | ||
+ | |||
+ | If you wish to reference a paper with a PMID, the full information can be automatically retrieved from PubMed for you. To create the reference, use the <tt><nowiki><</nowiki>ref></tt> tag: | ||
+ | |||
+ | <nowiki><</nowiki>ref name=PMID:15752432 /> | ||
+ | |||
+ | And put the tag <tt><nowiki><</nowiki>references /></tt> where you want the full references to appear on the page. The full details of each paper will magically appear in place of the <tt><nowiki><</nowiki>references /></tt> tag. | ||
[[Category:GMOD Web Site]] | [[Category:GMOD Web Site]] | ||
[[Category:Help]] | [[Category:Help]] |
Revision as of 00:52, 10 October 2012
This page discusses editorial policies and best practices to follow when updating or creating content in the GMOD web site.
Contents
Introduction
The GMOD web site editorial policies and best practices are defined here. Consistent use of these policies and practices will hopefully lead to a consistent and readable web site.
This page first introduces meta-guidelines. These are guidelines about these guidelines and cover things like how to update the guidelines, and when you can ignore them. These are followed by the actual guidelines, describing how content should be created.
Meta-Guidelines
Or, Guidelines on Guidelines.
Ignoring
Q: Can I ignore these guidelines?
A: Yes.
This is for pragmatic and philosophical reasons. The whole goal of a wiki is to encourage people to contribute and maintain content. Site guidelines encourage a clean and well organized web site, but if the guidelines discourage people from contributing in the first place, then they have defeated the whole purpose.
It also takes some time to become proficient at MediaWiki (the wiki package behind this web site), and it can be a challenge to learn MediaWiki details and site policies at the same time.
However, once you get comfortable with MediaWiki, please think about writing your content so it does conform to these standards.
Updating
These guidelines are a work in progress and you are encouraged to suggest additions, deletions or revisions to them. The best way to do this is to send your comments to the GMOD Help Desk. Alternatively, you can post them to this page (or to this page's discussion/talk page).
Enforcing
Q: Is there any enforcement of these guidelines?
A: Not really.
Beyond the usual wiki practices, there is no enforcement of these guidelines. This means that any non-conforming material you write won't be deleted, but it might be modified to follow the guidelines if and when somebody notices.
Guidelines
This is a list of guidelines for creating content in the GMOD web site. Some guidelines are accompanied by discussion that explains them.
Discussion is shown as regular text.
Page Names
Capitalization
For example, use "Site Guidelines" instead of "Site guidelines".
It looks better.
Redirects
This means that if a user types "Generic Genome Browser" in the "Go/Search" box and you have a redirect defined for "GBrowse" then they will go directly to the GBrowse page, instead of the search results page.
To create a redirect page, enter the name of the redirect page in the Go/Search box and hit enter. Then click on the "create this page" link. In our example, you would enter/search for "Generic Genome Browser".
This will display an empty page. Enter
#REDIRECT [[Page Name to Redirect to]]
In our example this would be:
#REDIRECT [[GBrowse]]
and then save the page.
A slight downside of this is that the Special:Allpages view now displays lots of pages that are only redirects to other pages. This turns into more of an index than a listing of all pages.
Minor vs Major Edits
When you update a page in this web site you can flag it as a minor edit. As of December 2007, the minor/major edit distinction is used in one place in the GMOD web site: Major edits (that is, edits that are not marked as minor) cause the page to be listed in the New & Revised Pages list on the GMOD home page. That list is a reverse chronological ordering of all recent non-minor edits
If your edit is small, such as a spelling or other typo correction, then mark it as a minor edit.
Tags / Categories
Be generous in your tagging. If a particular category gets too many pages in it then the help desk will subdivide that category.
This web site makes extensive use of tags, called categories in MediaWiki, to flag pages as being related to different topics. To encourage the use of categories, an input field and tag cloud listing existing categories is shown at the bottom of every edit page. You can either type in the category name or click on the category in the tag cloud to add it to the current page.
As of January, 2008 we are still adding category tags to pages. Once that work is closer to complete, categories will be prominently featured in site navigation.
New Categories
You can create a new category by typing the new category name in the Categories form on an edit page.
When creating a new category please:
- Check that the new category is not redundant with an existing category.
- Create a category only if it will apply to more than one page.
- Add the category to other pages that it applies to.
- Create the category page for the new category.
- Include a description of the category in the page.
- Also, make the new category a subcategory of any existing categories it could be a subcategory of.
- You do this by using, you guessed it, the Categories form on the edit page when creating the category page.
Or, just send your new category suggestion to the GMOD Help Desk and we will add it.
Uploading Files
Destination Filenames
The Destination filename is the name the file will have in the GMOD web site. Why does this matter? Filenames are displayed in Categories, but none of the text in the file is. Therefore the filename should describe the contents of the file.
For example, the file Gkl777.pdf is an article on ParameciumDB from Nucleic Acids Research, but if you look at the file's listing in the Publications category all you see is "Gkl777.pdf". You have to follow the link to find out what the file is about.
File Categories
If the file is an image that is being linked to from a page then you don't need to categorize it.
Diagrams and Cartoons
This will allow others (and yourself) to modify the diagrams in the future rather than recreate them from scratch.
Format
Please Note:
- These guidelines were first developed for the GMOD Courses, where these were used to format the Tutorial pages.
- If this seems daunting, please see Meta-Guideline #1: Ignoring, and hopefully feel better.
Descriptions of what formatting is desired and how to achieve it. For each type of text, this shows a minimum desired formatting, and, in most cases, a better (but more work) formatting.
Many of these are the result of questions and suggestions from past participants.
Type of text | Minimum | Better |
---|---|---|
|
Check the thingy.conf file. Check the thingy.conf file. |
Check the <tt>thingy.conf</tt> file. Check the thinigy.conf file. |
|
You can add a leading space on each line:
> "Pythium" for the default organism Or use pre tags: <pre> Available ontologies: [1] Relationship Ontology [2] Sequence Ontology [3] Gene Ontology [4] Chado Feature Properties [5] Cell Ontology [6] Plant Ontology </pre> > "Pythium" for the default organism Or Available ontologies: [1] Relationship Ontology [2] Sequence Ontology [3] Gene Ontology [4] Chado Feature Properties [5] Cell Ontology [6] Plant Ontology |
Same |
|
~/work/galaxy-dist$ head tool_conf.xml ~/work/galaxy-dist$ head tool_conf.xml |
~/work/galaxy-dist$ head tool_conf.xml
|
|
Edit the configuration file: gedit thingy.conf |
Edit the configuration file: gedit thingy.conf |
|
I dunno | I dunno either |
|
<pre> <tool id="get_flanks1" name="Get flanks"> <description> returns flanking region/s for genes </description> <command interpreter="python"> get_flanks.py $input ... </command> ...</pre> <tool id="get_flanks1" name="Get flanks"> <description> returns flanking region/s for genes </description> <command interpreter="python"> get_flanks.py $input ... </command> ... |
<syntaxhighlight lang="xml"> <tool id="get_flanks1" name="Get flanks"> <description> returns flanking region/s for genes </description> <command interpreter="python"> get_flanks.py $input ... </command> ...</syntaxhighlight> <tool id="get_flanks1" name="Get flanks"> <description> returns flanking region/s for genes </description> <command interpreter="python"> get_flanks.py $input ... </command> ... |
|
<div class="dont"> Here's an example of what ''not'' to do: cd /; sudo rm -rf * </div> Here's an example of what not to do: cd / sudo rm -rf * |
Same |
|
Now, to enable this theme, navigate to Administer, Site Building, Themes page and select the Pixture Reloaded radio button. |
Now, to enable this theme, navigate to the Administer → Site Building → Themes page and select the Pixture Reloaded button. |
Embedding Media
The GMOD wiki uses Widgets to embed various types of file.
Google Documents
{{#widget: GoogleDocument |id=<document ID> |width=<width> |height=<height> }}
Full documentation at Widget:GoogleDocument.
Google Presentations
{{#widget: GooglePresentation |id=<presentation ID> |width=<width> |height=<height> |border=<border> }}
Full documentation at Widget:GooglePresentation.
Google Calendars
{{#widget :GoogleCalendar |id=usa@holiday.calendar.google.com |color=B1440E |title=US Holidays }}
Full documentation at Widget:GoogleCalendar.
Flash
To embed Flash into a page, use the following syntax:
<oflash file="File:Movie.swf" caption="A cool flash movie that I made" width=500 height=900 />
More documentation on the OFlash MediaWiki page.
Writing Code
The GMOD wiki employs the extension Syntax Highlight GeSHi to produce code with highlighting. For coloured code, use the < syntaxhighlight> tag:
< syntaxhighlight lang="perl"> #!/usr/bin/perl my $life = "over"; die("Goodbye, cruel world!"); </syntaxhighlight>
#!/usr/bin/perl my $life = "over"; die("Goodbye, cruel world!");
Languages supported include Javascript, Java, Perl, PHP, XML, CSS, and more. Full documentation can be found on the Syntax Highlight GeSHi MediaWiki page.
Adding References
If you wish to reference a paper with a PMID, the full information can be automatically retrieved from PubMed for you. To create the reference, use the <ref> tag:
<ref name=PMID:15752432 />
And put the tag <references /> where you want the full references to appear on the page. The full details of each paper will magically appear in place of the <references /> tag.