Difference between revisions of "User:Kutschke/Draft WikiTips"
| (5 intermediate revisions by the same user not shown) | |||
| Line 34: | Line 34: | ||
=User Pages= | =User Pages= | ||
| − | User pages can be used to present your own work. Be sure to choose wisely about putting information in the public or private wiki. All Mu2e members can edit others User page so be careful with pages that are | + | User pages can be used to present your own work. Be sure to choose wisely about putting information in the public or private wiki. All Mu2e members can edit others User page so be careful with pages that are not your own. |
Every wiki user can create their own User page. To see your own User page, log in to the wiki and click on your username in the upper right of the page. If the page does not yet exist, you will be prompted to create it. | Every wiki user can create their own User page. To see your own User page, log in to the wiki and click on your username in the upper right of the page. If the page does not yet exist, you will be prompted to create it. | ||
| Line 51: | Line 51: | ||
MediaWiki does not have good support for draft pages. We suggest that you create a draft page in your User area. Others can see it an edit it. When the page is ready, edit the page and copy the content into the edit window of the destination page in the main namespace. | MediaWiki does not have good support for draft pages. We suggest that you create a draft page in your User area. Others can see it an edit it. When the page is ready, edit the page and copy the content into the edit window of the destination page in the main namespace. | ||
| − | All pages also have an associated Discussion page. It's a separate tab at the top left of the page. Click on it to see the discussion or create it if it does not yet exit. People can use this to discuss the content on the page. Your call on how to use | + | All pages also have an associated Discussion page. It's a separate tab at the top left of the page. Click on it to see the discussion or create it if it does not yet exit. People can use this to discuss the content on the page. Your call on how to use the discussion page. Often an email exchange will be all your need, particularly if the discussion has no archival value. |
=Adding Figures= | =Adding Figures= | ||
| − | To add a figure to a page, you need to make sure that the figure file has been uploaded to the wiki. Click on the Special Pages link in the left sidebar. From there click on the "File list" link under "Media and uploads". Check to see if your figure has already been uploaded. If not | + | To add a figure to a page, you need to make sure that the figure file has been uploaded to the wiki. Click on the Special Pages link in the left sidebar. From there click on the "File list" link under "Media and uploads". Check to see if your figure has already been uploaded. If not, you will need to upload it. To do that, click on the "Upload file" link in the left sidebar and follow the instructions to upload your file. |
There are instructions on the upload page for how to refer to the figure on a wiki page. You can also use [[DetectorIntro]] as a model. | There are instructions on the upload page for how to refer to the figure on a wiki page. You can also use [[DetectorIntro]] as a model. | ||
| Line 81: | Line 81: | ||
Clicking the star toggles the state. | Clicking the star toggles the state. | ||
| − | On your Preferences page you can choose to be notified by email whenever a page on your watch list changes. | + | On your Preferences page you can choose to be notified by email whenever a page on your watch list changes. You can also choose that any page you edit is put on your watchlist. |
You can control some features of your watchlist on your User Preferences page. See [[#User Preferences etc]]. | You can control some features of your watchlist on your User Preferences page. See [[#User Preferences etc]]. | ||
| Line 89: | Line 89: | ||
=Tips for Version Dependent Content= | =Tips for Version Dependent Content= | ||
| − | If you are documenting software or an analysis technique, many details may be version dependent. We suggest that you use the wiki to document that material that is common to all versions and to use a GitHub repo to hold the version dependent parts of the documentation. This provides a structure to keep documentation in sync with evolving details. Don't forget to update the documentation when you update the code. | + | If you are documenting software or an analysis technique, many details may be version dependent. We suggest that you use the wiki to document that material that is common to all versions and to use a GitHub repo to hold the version dependent parts of the documentation. Then link to this material from the wiki. This provides a structure to keep documentation in sync with evolving details. Don't forget to update the documentation when you update the code. |
| + | |||
| + | You can also choose to put everything in the GitHub repo with a short introduction on the wiki. | ||
| + | |||
| + | As always, be wise about choosing to put content in a public or private area. | ||
For an example, see the documentation for the [https://github.com/Mu2e/Tutorial/blob/main/AllInOne/doc/AllInOne.md Software Tutorial]. | For an example, see the documentation for the [https://github.com/Mu2e/Tutorial/blob/main/AllInOne/doc/AllInOne.md Software Tutorial]. | ||
=Deleting and Redirecting Pages= | =Deleting and Redirecting Pages= | ||
| + | |||
| + | When you are logged in the wiki, look on the top right, immediately to the left of the search box for a pull down menu named "More". When you expand this menu, you will see 3 options, Delete, Move and Protect. | ||
| + | |||
| + | If you wish to delete a page, click on the "Delete" option. This will bring you to a page that asks you to document why you are deleting the page and a button to complete the process. We suggest that before, you delete a page, you check what links to it and make plans to update those links. If there are many links you may want to make a different plan. Perhaps you could replace the content with a statement that a page is obsolete plus suggested links to successor content? | ||
| + | |||
| + | However delete does not really mean delete. When you delete a page, it is effectively moved to a Trash bin. If there are still links to the page and you follow one of those links you will be brought to a page that offers to restore the deleted page. You can view all deleted pages by selecting "View deleted pages" link from the "Special pages" link in the left sidebar. | ||
| + | |||
| + | If we need to really delete content, perhaps because the page contains information that is not meant to be public, we need first delete the page and then open a service desk ticket to request full deletion.. | ||
| + | |||
| + | If you want to rename a page, click on the "Move" link from the pull down menu. This will bring you to a page that will let you do the rename, including renaming it to a different namespace. The page comes with a pre-checked box to leave behind a redirect link so that links to the old url will auto-forward to the new url. Normally you should leave this box checked. | ||
=Forcing a Table of Contents= | =Forcing a Table of Contents= | ||
If you have three or fewer headings but want to have a TOC, write either the magic word <pre>__FORCETOC__</pre> anywhere on the page to make it display at the default location, or <pre>__TOC__</pre> at the preferred position. | If you have three or fewer headings but want to have a TOC, write either the magic word <pre>__FORCETOC__</pre> anywhere on the page to make it display at the default location, or <pre>__TOC__</pre> at the preferred position. | ||
Latest revision as of 14:32, 3 May 2024
This page contains background information about the Mu2e wiki and tips for using it.
Introduction
The Mu2e wiki is an instance of MediaWiki that is supported by the Fermilab Information Technology Division (ITD). ITD maintains MediaWiki instances for many experiments and projects. In the interest of keeping things simple to manage they will not install WikiMedia extensions so we are missing some useful functionality. Among the extensions they will not install is that extension that would allow us to make pages public/private on a per page basis. Instead we have one public wiki and one private wiki. There are also separate public and private wikis for Mu2e-II. Look a the top of the left sidebar for links to all 4 wikis.
The public wiki is readonly visible to the general public and is editable by Mu2e members. To be recognized as a Mu2e member you need to log in. Look for a link named "Log in" in the upper right of the page. Use your services password.
The private wiki is readable and editable by Mu2e members. Similarly for the Mu2e-II public and private wikis. There is a separate membership list for the Mu2e-II wiki.
It is possible for Mu2e admins to install MediaWiki Templates. For example the Anchor Template is used in the Glossary.
In the middle section of the left side bar, there is a "Help" link, which takes you to the main MediaWiki online help. Everything you need to know is there but it might take a little work to find it. One strategy is to google the string Mediawiki along with the topic you are looking to find. This will often find the correct page within the MediaWiki online help and it might find useful information from a third party page. And you can ask a question on a Mu2e slack channel.
Two other useful links in the left sidebar are "What links here" and "Special Pages". The former tells you which pages in the wiki link to the current page. The latter lets you do things like find a list of all pages in the wiki, see the list of all the pages you are watching (see #Watching Pages), check for broken links, look for pages that are orphaned (ie not linked from another page), and so on.
The rest of this page gives some tips for effective use of the wiki that might take some time to find in the online Help.
User Preferences etc
When you are logged in to the Mu2e wiki, there 5 links on the upper right of the page.
- Your username. Click on this go to your User page. If your User page does not exist you will see a link to create it.
- "Talk". Click on this to go to your talk page. If your talk page does not exist, you will see a link to create it. See [1].
- "Preferences". This will bring you to a page with many tabs to customize the way you interact with the wiki.
- "Watchlist". This shows a list of recent changes on pages that you are watching. Details can be customized in preferences.
- "Contributions". This shows a history of pages you have modified.
Search Tips
If you want to search for a multiword phrase, enclose the phrase in quotes. If you leave it unquoted it will search for the OR of the words.
User Pages
User pages can be used to present your own work. Be sure to choose wisely about putting information in the public or private wiki. All Mu2e members can edit others User page so be careful with pages that are not your own.
Every wiki user can create their own User page. To see your own User page, log in to the wiki and click on your username in the upper right of the page. If the page does not yet exist, you will be prompted to create it.
You can also navigate to your, or anyone else's User page using the url https://mu2ewiki.fnal.gov/wiki/User:Username, where Username is a place holder for a wiki user's username and where the rest of the text should be typed as is.
If you are not sure of the spelling of someone's username, you can click on the "Special Pages" link in the left hand sidebar. On that page, click on the "User list" link. Navigate to their username and click on it. If they have User page this will bring you to it.
To create a sub page of your User page, you need to include the User:Username namespace and username. For example, if you add the following text to your user page,
[[User:Username/NewPage]]
and click on it, it will take you to a new page with a link to create subpage named NewPage on the User page for the user Username. You may also make sub pages of subpages.
Draft Pages
MediaWiki does not have good support for draft pages. We suggest that you create a draft page in your User area. Others can see it an edit it. When the page is ready, edit the page and copy the content into the edit window of the destination page in the main namespace.
All pages also have an associated Discussion page. It's a separate tab at the top left of the page. Click on it to see the discussion or create it if it does not yet exit. People can use this to discuss the content on the page. Your call on how to use the discussion page. Often an email exchange will be all your need, particularly if the discussion has no archival value.
Adding Figures
To add a figure to a page, you need to make sure that the figure file has been uploaded to the wiki. Click on the Special Pages link in the left sidebar. From there click on the "File list" link under "Media and uploads". Check to see if your figure has already been uploaded. If not, you will need to upload it. To do that, click on the "Upload file" link in the left sidebar and follow the instructions to upload your file.
There are instructions on the upload page for how to refer to the figure on a wiki page. You can also use DetectorIntro as a model.
Tables
The wiki help for tables is at: https://www.mediawiki.org/wiki/Help:Tables.
An example table, a fairly complex one, is at Disks#Introduction.
Greek Fonts
The Mu2e wiki support MathJax, a TeX-like markup language. Some examples:
- Inline: [math]\displaystyle{ (\varphi,\theta,-\varphi) }[/math]
- Inline: [math]\displaystyle{ x = {-b \pm \sqrt{b^2-4ac} \over 2a} }[/math]
- Block quote: $$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$$
Watching Pages
You can sign up to be notified whenever changes are made to a page. On the top right of each page, between the "View history" button and the "More" button is a star. If the star is blue-filled, you are watching the page and will be notified by email when it changes. If the star is empty, you are not on the watchlist for the page. Clicking the star toggles the state.
On your Preferences page you can choose to be notified by email whenever a page on your watch list changes. You can also choose that any page you edit is put on your watchlist.
You can control some features of your watchlist on your User Preferences page. See #User Preferences etc.
You can read more about watch lists at [https://www.mediawiki.org/wiki/Help:Watchlist.
Tips for Version Dependent Content
If you are documenting software or an analysis technique, many details may be version dependent. We suggest that you use the wiki to document that material that is common to all versions and to use a GitHub repo to hold the version dependent parts of the documentation. Then link to this material from the wiki. This provides a structure to keep documentation in sync with evolving details. Don't forget to update the documentation when you update the code.
You can also choose to put everything in the GitHub repo with a short introduction on the wiki.
As always, be wise about choosing to put content in a public or private area.
For an example, see the documentation for the Software Tutorial.
Deleting and Redirecting Pages
When you are logged in the wiki, look on the top right, immediately to the left of the search box for a pull down menu named "More". When you expand this menu, you will see 3 options, Delete, Move and Protect.
If you wish to delete a page, click on the "Delete" option. This will bring you to a page that asks you to document why you are deleting the page and a button to complete the process. We suggest that before, you delete a page, you check what links to it and make plans to update those links. If there are many links you may want to make a different plan. Perhaps you could replace the content with a statement that a page is obsolete plus suggested links to successor content?
However delete does not really mean delete. When you delete a page, it is effectively moved to a Trash bin. If there are still links to the page and you follow one of those links you will be brought to a page that offers to restore the deleted page. You can view all deleted pages by selecting "View deleted pages" link from the "Special pages" link in the left sidebar.
If we need to really delete content, perhaps because the page contains information that is not meant to be public, we need first delete the page and then open a service desk ticket to request full deletion..
If you want to rename a page, click on the "Move" link from the pull down menu. This will bring you to a page that will let you do the rename, including renaming it to a different namespace. The page comes with a pre-checked box to leave behind a redirect link so that links to the old url will auto-forward to the new url. Normally you should leave this box checked.
Forcing a Table of Contents
If you have three or fewer headings but want to have a TOC, write either the magic word
__FORCETOC__
anywhere on the page to make it display at the default location, or
__TOC__
at the preferred position.