Difference between revisions of "How to write an article"

From VSI OpenVMS Wiki
Jump to: navigation, search
(→‎Linking)
 
(2 intermediate revisions by one other user not shown)
Line 7: Line 7:
 
=Starting=
 
=Starting=
  
−
If you have chosen one of the wanted pages or there is a red link to the topic of your choice elsewhere, click that link - you will be redirected to the editing area. Otherwise enter the topic of your choice into the search bar and hit enter - if there is no article with this name, there will be a red link leading you to the editing area. If there is already an article with this name, you can expand that article instead. In any case you need to be logged in to edit articles in this wiki. If you don't have login credentials, please contact training@vmssoftware.com for a registration.
+
If you have chosen one of the wanted pages or there is a red link to the topic of your choice elsewhere, click that link. You will be redirected to the editing area. Otherwise enter the topic of your choice into the search bar and hit enter. If there is no article with this name, there will be a red link leading you to the editing area. If there is already an article with this name, you can expand that article instead.  
 +
 
 +
In any case you need to be logged in to edit articles in this wiki. If you are registered at [https://training.vmssoftware.com/ the VSI Training website], click "Log in" on the wiki and enter your credentials. If you are not registered at the training website, register [https://training.vmssoftware.com/login/signup.php here], then log in on the training website, return to this wiki and click "Log in"; you will be logged in automatically.
 +
 
 +
After you are done with the edits, click "Save changes" at the bottom of the Editing page. You can also click "Show preview" to see what the final page would look like. However, this does not save your edits, so the changes are not visible to the general public until you save them.
  
 
=Style=
 
=Style=
Line 281: Line 285:
  
 
=Linking=
 
=Linking=
 +
 +
To create a link to an external resource, use single square brackets. You can insert an optional link text after a whitespace inside the brackets:
 +
 +
<nowiki>[https://support.hpe.com/hpsc/doc/public/display?docId=emr_na-c04623201 OpenVMS System Services Reference Manual]</nowiki>
 +
 +
The code above will look like this:
 +
 +
[https://support.hpe.com/hpsc/doc/public/display?docId=emr_na-c04623201 OpenVMS System Services Reference Manual]
 +
 +
To create a link to a page of this wiki, use double square brackets. You can insert an optional link text after a vertical bar "|" inside the brackets:
 +
 +
<nowiki>[[System Service|System service page]]</nowiki>
 +
 +
The code above will look like this:
 +
 +
[[System Service|System service page]]
 +
 +
To create a link to a section in this article, use double square brackets and a pound sign ("#"). You can insert an optional link text after a vertical bar "|" inside the brackets:
 +
 +
<nowiki>[[#Wiki Markup|Wiki markup section]]</nowiki>
 +
 +
The code above will look like this:
 +
 +
[[#Wiki Markup|Wiki markup section]]
  
 
It is a good practice to point the readers to the relevant documentation using footnotes or the "See also" section. Use the following code to add links to the documentation:
 
It is a good practice to point the readers to the relevant documentation using footnotes or the "See also" section. Use the following code to add links to the documentation:
Line 287: Line 315:
 
! scope="col;" | For this document...
 
! scope="col;" | For this document...
 
! scope="col;" | ...insert this code
 
! scope="col;" | ...insert this code
 +
|-
 +
|
 +
{{Template:Cluster}}
 +
| <nowiki>
 +
{{Template:Cluster}}
 +
</nowiki>
 
|-
 
|-
 
|
 
|
Line 298: Line 332:
 
| <nowiki>
 
| <nowiki>
 
{{Template:DCLII}}
 
{{Template:DCLII}}
 +
</nowiki>
 +
|-
 +
|
 +
{{Template:EDT}}
 +
| <nowiki>
 +
{{Template:EDT}}
 +
</nowiki>
 +
|-
 +
|
 +
{{Template:EVE}}
 +
| <nowiki>
 +
{{Template:EVE}}
 +
</nowiki>
 +
|-
 +
|
 +
{{Template:Fap}}
 +
| <nowiki>
 +
{{Template:Fap}}
 +
</nowiki>
 +
|-
 +
|
 +
{{Template:IO}}
 +
| <nowiki>
 +
{{Template:IO}}
 +
</nowiki>
 +
|-
 +
|
 +
{{Template:Sec}}
 +
| <nowiki>
 +
{{Template:Sec}}
 
  </nowiki>
 
  </nowiki>
 
|-
 
|-
Line 304: Line 368:
 
| <nowiki>
 
| <nowiki>
 
{{Template:SyservI}}
 
{{Template:SyservI}}
 +
</nowiki>
 +
|-
 +
|
 +
{{Template:SyservII}}
 +
| <nowiki>
 +
{{Template:SyservII}}
 
  </nowiki>
 
  </nowiki>
 
|-
 
|-
Line 343: Line 413:
 
  </nowiki>
 
  </nowiki>
  
−
=See also=
+
The list from the example above will appear as:
 
* {{Template:DCLI}}
 
* {{Template:DCLI}}
 
* {{Template:SysmanI}}
 
* {{Template:SysmanI}}
  
 
=Categories=
 
=Categories=
 +
 +
To improve searcheability of the wiki, please add categories to your articles. This is done using the following code:
 +
 +
<nowiki>[[Category:NameofYourCategory]]</nowiki>
 +
 +
This text appears as a box with the link to the category. The link is red if the category does not exist.

Latest revision as of 10:16, 20 October 2022

This page describes how to write articles in this wiki, including content and style guides.

Choosing a Topic

You can write an article on any topic connected with OpenVMS. If you don't have ideas, browse our wanted pages - these are pages that the existing articles have links to. A good topic is one you can write at least 500 words about.

Starting

If you have chosen one of the wanted pages or there is a red link to the topic of your choice elsewhere, click that link. You will be redirected to the editing area. Otherwise enter the topic of your choice into the search bar and hit enter. If there is no article with this name, there will be a red link leading you to the editing area. If there is already an article with this name, you can expand that article instead.

In any case you need to be logged in to edit articles in this wiki. If you are registered at the VSI Training website, click "Log in" on the wiki and enter your credentials. If you are not registered at the training website, register here, then log in on the training website, return to this wiki and click "Log in"; you will be logged in automatically.

After you are done with the edits, click "Save changes" at the bottom of the Editing page. You can also click "Show preview" to see what the final page would look like. However, this does not save your edits, so the changes are not visible to the general public until you save them.

Style

Please follow this style guide when writing your articles:

Capitalization

The title of the article and all of the subtitles should be capitalized: "Logical Names" is a good name, "logical names" is not. The title of the article used in the beginning of the article also needs to be bolded: 

Logical Names
Logical names are arbitrary strings...

Names of the OpenVMS utilities and files should be in uppercase: ADDUSER.COM, LGI_BRK_LIM, etc.

Wiki Markup

Use this quick guide below or this long guide on the MediaWiki website.

Bold/Italics/Underlined

Effect You enter Result
bold '''bold''' bold
italics ''italics'' italics
bold and italics '''''bold and italics''''' bold and italics
underlined <u>underlined</u> <underlined

Sections

Use the following markup for sections: 

=Section=
==Subsection==
===Sub-subsection===

The collapsible Contents box is created automatically.

Representing code

To represent code, start each line with a whitespace or put it inside of a tag (the tag lines should also start with a whitespace!) 

$! test.com
$ write sys$output "Hello!"

Collapsible Elements

You can insert long command procedures without harming the structure or readability of your articles using collapsible elements:

Text that describes the collapsible element

Contents of the collapsible element

To insert the element above, use the following code: 

<div class="toccolours mw-collapsible mw-collapsed" data-expandtext="{{int:show}}" data-collapsetext="{{int:hide}}" style="width:800px; overflow:auto;">
Text that describes the collapsible element
<div class="mw-collapsible-content">
Contents of the collapsible element
</div>
</div>

Tables

Mediawiki manual on tables

If you want to create a table with borders, use class="wikitable":

You enter You get 
 {| class="wikitable"
 | your first column
 | your second column
 |-
 | row 1
 | row 1
 |-
 | row 2
 | row 2
 |}
your first column your second column
row 1 row 1
row 2 row 2

If you want a table without borders, remove the class="wikitable" part.

If you want to emphasize the first row of the table (if it contains column title), use "! scope='col';" before the vertical bar in the title of each column:

You enter You get 
 {| class="wikitable"
 ! scope='col'; | your first column
 ! scope='col';| your second column
 |-
 | row 1
 | row 1
 |-
 | row 2
 | row 2
 |}
your first column your second column
row 1 row 1
row 2 row 2

If you want to merge cells, use the colspan and rowspan attributes:

You enter You get 
 {| class="wikitable"
 ! scope='col'; | your first column
 ! scope='col';| your second column
 ! scope='col';| your third column
 |-
 | colspan="2;"| row 1
 | rowspan="3;"| row 1
 |-
 | row 2
 | row 2
 |}
your first column your second column your third column
row 1 row 1
row 2 row 2

You can change attributes of the entire table in the first row where class="wikitable" appears:

You enter You get 
 {| class="wikitable" style="color:green; background-color:#ffffcc;" cellpadding="10"
 | your first column
 | your second column
 |-
 | row 1
 | row 1
 |-
 | row 2
 | row 2
 |}
your first column your second column
row 1 row 1
row 2 row 2

You can also change attributes of a cell:

You enter You get 
 {| class="wikitable" 
 | your first column
 | style="background-color:#ffffcc;"| your second column
 |-
 | row 1
 | row 1
 |-
 | row 2
 | row 2
 |}
your first column your second column
row 1 row 1
row 2 row 2

The attributes that you can change include:

  • float:left/right and vertical-align:top/bottom control where the table appears on the page (e.g. style="float:right;", style="vertical-align:bottom;")
  • height controls the height of the table (e.g. style="height:50px";)
  • width controls the width of the table (e.g. style="width:400px";)
  • margin-left and margin-right control where the table appears on the screen (e.g. style="margin-left: auto; margin-right: 0px;)
  • text-align:left/right/center controls how text is aligned (e.g. style="text-align:center;")
  • color controls the color of the text (e.g. style="color:green")
  • background-color controls the background color of the table (e.g. style="background-color:white;" style="background-color:#ffffcc;")
  • font-style controls the font style (e.g. style="font-style:italic;")
  • border-width: controls border width (e.g. style="border-width:20px;")
  • border-left/right/top/bottom control the border of each cell (e.g. "border-left:solid 10px black;")
  • cellpadding controls how much space is left between the text and the border of the cell (e.g. cellpadding="10;")

Note that you only need to include the word "style" once: 

style="color:green; background-color:#ffffcc;" cellpadding="10"

Linking

To create a link to an external resource, use single square brackets. You can insert an optional link text after a whitespace inside the brackets: 

[https://support.hpe.com/hpsc/doc/public/display?docId=emr_na-c04623201 OpenVMS System Services Reference Manual]

The code above will look like this:

OpenVMS System Services Reference Manual

To create a link to a page of this wiki, use double square brackets. You can insert an optional link text after a vertical bar "|" inside the brackets: 

[[System Service|System service page]]

The code above will look like this:

System service page

To create a link to a section in this article, use double square brackets and a pound sign ("#"). You can insert an optional link text after a vertical bar "|" inside the brackets: 

[[#Wiki Markup|Wiki markup section]]

The code above will look like this:

Wiki markup section

It is a good practice to point the readers to the relevant documentation using footnotes or the "See also" section. Use the following code to add links to the documentation:

For this document... ...insert this code

VSI OpenVMS Cluster Systems

{{Template:Cluster}}

OpenVMS DCL Dictionary Vol. I (A-M)

{{Template:DCLI}}

OpenVMS DCL Dictionary Vol. II (N-Z)

{{Template:DCLII}}

OpenVMS EDT Reference Manual

{{Template:EDT}}

Extensible Versatile Editor Reference Manual

{{Template:EVE}}

Guide to OpenVMS File Applications

{{Template:Fap}}

OpenVMS I/O User's Reference Manual

{{Template:IO}}

OpenVMS Guide to System Security

{{Template:Sec}}

OpenVMS System Services Reference Manual Vol. I (A-GETUAI)

{{Template:SyservI}}

OpenVMS System Services Reference Manual Vol. II (GETUTC-Z)

{{Template:SyservII}}

OpenVMS System Manager's Manual Vol. I

{{Template:SysmanI}}

OpenVMS System Manager's Manual Vol. II

{{Template:SysmanII}}

OpenVMS User's Manual

{{Template:Userman}}

OpenVMS System Management Utilities Reference Manual Vol. I (A-L)

{{Template:UtilitiesI}}

OpenVMS System Management Utilities Reference Manual Vol. II (M-Z)

{{Template:UtilitiesII}}

For example: 

* {{Template:DCLI}}
* {{Template:SysmanI}}

The list from the example above will appear as:

Categories

To improve searcheability of the wiki, please add categories to your articles. This is done using the following code: 

[[Category:NameofYourCategory]]

This text appears as a box with the link to the category. The link is red if the category does not exist.

Retrieved from "https://wiki.vmssoftware.com/index.php?title=How_to_write_an_article&oldid=2542"