PrF UG help all

From Protege Wiki
Revision as of 02:15, November 19, 2008 by RichMorin (talk | contribs) (New page: <noinclude>{{PrF_UG}}__TOC__<div id='prf_ug'></noinclude> {{:PrF_UG_help}} {{:PrF_UG_help_user_howto}} {{:PrF_UG_help_admin_howto}} {{:PrF_UG_help_admin_theory}} <noinclude></div> [[Catego...)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Help

This section of the User's Guide provides help on using and editing the guide. Some pages are aimed at general users; others are intended to help administrators.

Note: As a user of this guide, you are welcome to make changes and additions to its content. However, before you attempt to make administrative changes (e.g., renaming pages, changing the page format), please get explicit authorization by the BMIR staff!

To return to the main table of contents, click the Protege-Frames User's Guide link (located at the top of the table of contents on the right-hand side of this page).


User HowTo

If you are comfortable browsing web pages, you should have no difficulty using our "wikified" User's Guide. From the perspective of a user who only wants to read the guide, it's just a set of web pages (with content, clickable links, etc).

However, because the guide is actually a set of wiki pages, you are allowed (nay, encouraged) to make your own contributions. This page will give you some ideas about how to go about this.

Note: Please review this material, even if you are a seasoned wiki user, as it contains some information specific to the guide.

Wiki Notes

The "wiki engine" we're using is MediaWiki, best known as the engine used for Wikipedia. MediaWiki is a mature, well-supported wiki engine, with a number of useful features. Some of these require careful handling, however, so we ask that you act cautiously in editing anything you aren't sure you understand.

If you are new to wikis in general and/or MediaWiki in particular, you should approach your initial editing sessions with a bit of caution. Print out a copy of the page you wish to edit, so that you know how it looked when you started. By comparing this page to the "markup text" on the editing page, you can see which markup produces which formatting effects.

Ordinary paragraph text is simple and relatively safe to edit. Links can be tricky to get right, but if they render properly and go to the right page, you're OK. Bullet lists and tables, on the other hand, can be seriously difficult to edit correctly. Finally, the mysterious incantations at the top and bottom of each Content page should be left alone (really).

If you aren't sure you know what you're doing, don't be afraid to ask for help! The BMIR staff will happily assist you with any questions. Also, bearing in mind the fact that the Guide is not part of Wikipedia, you can still find a great deal of useful information in the Wikipedia help pages.

Page Types

For our purposes, the guide is composed of four page types:

  • Aggregate - used for printing, scanning, searching, etc.
  • Content - used for the guide's actual content
  • Discussion - used for comments, questions, etc.
  • Template - used for formatting information, etc.

Aggregate Pages

Aggregate pages contain concatenated sets of Content pages. If you want to print a Chapter (or the entire Guide), an Aggregate page is your best option. In addition, by loading an Aggregate page into your browser, you will be able to scan or search the material for desired content.

It should seldom be necessary for a user to edit an Aggregate page. They should only be edited when a Content page has been added, deleted, or renamed. Any of these actions should be cleared in advance with the BMIR staff.

Content Pages

Most of the pages in the Guide are Content pages. They contain text, diagrams, etc. If you see a way that a Content page could be improved, and feel confident in making the change, please feel free to do so!

Discussion Pages

If you find that a page needs some help, but aren't exactly sure how it should be changed, use the accompanying Discussion page to add a comment or question. Just click the "discussion" tab at the top of the relevant Content page, then add your comment and save the page. Your comments won't get in the way of regular users and they may well help to make the Guide better for everyone!

Template Pages

Template pages are used for formatting information, navigational sidebars, etc.

It should seldom be necessary for a user to edit a Template page. They should only be edited when the format of the wiki needs modification or a Content page has been added, deleted, or renamed. Any of these actions should be cleared in advance with the BMIR staff.



Admin HowTo

Aside from cleaning up problems caused by imprudent editing, the guide should be require little administration. The main difficulties will be associated with structural changes, such as when a page is added, deleted, or renamed.

Adding Pages

Adding a page is the simplest case, because no existing links will need to be changed. However, there are still a few details to consider.

The first consideration is page naming. Decide which chapter the page belongs in, then choose an unused name that follows the same pattern as existing pages in that chapter. For example, this page is named PrF_UG_help_admin_howto. The first part of the name (PrF_UG_help) indicates that it is part of the Protege-Frames User's Guide "Help" chapter. The remainder of the name (admin_howto) is mnemonic of the page topic.

When a new page (eg, PrF_UG_help_overview) is added, it should be listed in the relevant Aggregate (PrF_UG_help_all) and Template (Template:PrF_UG_TOC_help) pages. This isn't hard to do; just decide where the page should appear in the Table of Contents sidebar and edit the two files so that it shows up in the right position in both. Finally, add links in other pages, as appropriate.

Deleting Pages

If a page no longer has a valid purpose, or it seems appropriate to merge pages, you may need to delete a page. Removing the page's entries from the relevant Aggregate and Template pages is easy. The tricky part is finding all the other pages which mention the deleted page. Fortunately, MediaWiki provides a "special" page for this exact purpose. Let's assume you need to delete PrF_UG_foo_bar:

  • Go to Special:WhatLinksHere.
  • Enter page name (PrF_UG_foo_bar) in the Page field.
  • Click the Go button.
  • Follow the listed links and edit the pages as needed.
  • Try another search, as a sanity check!

Renaming Pages

The exact page name, as used by MediaWiki, does not have to bear any strong relationship to the page's title or topic. In fact, some of the current page names are already a bit fuzzy in that regard. So, you're probably better off living with a funky page name than going through the hassle and risk of changing it.

However, if you really need to change a page name, the simplest strategy is probably to add a new page, copying over the old page's content. Then, delete the old page. Of course, it's up to you to update all the relevant tables and links.



Admin Theory

No changes have been made to the basic MediaWiki software to support the Protege-Frames User's Guide. However, there are a few pages which need to be kept in mind.

Aggregate Pages

Each Aggregate page contains an ordered list of other pages. Most Aggregate pages (eg, PrF_UG_help_all) list Content pages. However, one Aggregate page (PrF_UG_all) lists other Aggregate pages.

The noinclude tags are used within included pages to prevent unwanted material from being included in a higher-level aggregation.

Template Pages

Each chapter has its own Template page (eg, Template:PrF_UG_TOC_help). This page defines the TOC (Table of Contents) sidebar and some formatting information for the associated Content pages.

CSS Definitions

At present, all of the Guide's CSS definitions are stored in MediaWiki:Common.css. The prf_ug and prf_ug_sb class attributes are used to constrain the effects of these definitions to pages in the Guide. Some single letter id attributes (eg, td.a, ul.a) are also used, but are "guarded" by the aforementioned class attributes.