Manualguidelines.Html - Revision history

Conversion script: link fix

2006-01-22T02:33:21Z

link fix

New page

== INKSCAPE MANUAL : GUIDELINES FOR AUTHORS AND TRANSLATORS ==

=== Style Guide ===

This Manual of Style has the simple purpose of making things easy to read by following a consistent format — it is a style guide. The following rules don't claim to be the last word. One way is often as good as another, but if everyone does it the same way, user documentation will be easier to read and use, not to mention easier to write and edit. In this regard the following quote from The Chicago Manual of Style deserves notice:

"Rules and regulations such as these, in the nature of the case, cannot be endowed
with the fixity of rock-ribbed law. They are meant for the average case, and must
be applied with a certain degree of elasticity."

(Above quoted from [http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style Wikipedia:Manual Of Style])

* Refer to the terms defined at [[InkscapeTerminology | Inkscape Terminology]]
* Use good writing and documentation practices and maintain a neutral point of view
* Write in a platform and hardware agnostic view, delineate differences where appropriate in a neutral way
* Do not use first or second person pronouns, i.e, I, you, etc.
* Refer to users as "Inkscape artists" or simply, "artists"
* Remain consistent in terminology
* Keys on the keyboard are never "button" they are always "key"
* The Control key should be written "Ctrl"
* Key combinations should be written "Ctrl+Alt+Shift+<key>"
* Tool names capitalize each word before "tool" but "tool" is not a proper noun and is not capitalized
* A panel in the Document window is a "bar" (Tool Controls bar) and is not concatenated with the name, (i.e., "Status bar" not "Statusbar")
* A "dialog" is a confirmation window, while other option dialogs are referred to as "window," and "window" is not capitalized
* Refer to Menu selections with the ">" separator, a users "selects" a Menu "option" (or "command") and where possible include the keyboard shortcut in parentheses immediately after. For example: "...and then select Path>Object To Path (Shift+Ctrl+C) or if the..." It is not desirable to use the "/" character to denote levels of the Menu since / appears in the Menu and > does not. Capitalize each Menu option.

Help file should be minimally structured to make it easy to use and comprehend. We propose that each page should be structured according to the base:

1. Tool Name or Page Theme name
2. Image (screenshot of a dialog ...)
3. Methods for tool activation, eventually with step by step demonstration
4. Keydings, modifiers , eventually with step by step demonstration
5. Tool options, eventually with a screenshot of the Dialog, and , eventually with step by step demonstration
6. Additionnal Information
7. Links to other related pages

=== [[DocBook]] ===

We have decided to use, for good compliance, the most popular documentation system present in [[OpenSource]]. Help file may be written in Docbook (the XML one) format, that can be converted with different tools. For more informations, follow the links placed at the end of this page.

Help Structure

The structure has been ported to be a huge big file to more easier to keep up-to-date. The past structure in multiple files is deprecated.

The file is begin as <book> containing bookinfo in which authors can put their name.
After that come parts :
<part> are used for :
* menu description
* themes access

Part may include chapters :
<chapter> are used for :
* menu item
* general subdivision

Then chapter include sect1 or simplesect (simplesect may be changed to sect1 if possible)
<sect1> are used for :
* internal section in a single page, when all theses sections refers to the same object or menu

Help file should be minimally structured to make it easy to use and comprehend. We propose that each page should be structured according to the base:

1. Tool Name or Page Theme name
2. Image (screenshot of a dialog ...)
3. Methods for tool activation, eventually with step by step demonstration
4. Keydings, modifiers , eventually with step by step demonstration
5. Tool options, eventually with a screenshot of the Dialog, and , eventually with step by step demonstration
6. Additionnal Information
7. Links to other related pages

[[DocBook]] Tags

Please, have a look at the Docbook Advice page and to the Websites listed below.

We also ask that contributors make a good use of indentation, in order to have more readable and useable source files.

1. Each tag containing visitor-readable-text should be placed on a new line with an additional indent;
2. Open and close tag of an element should be placed in the same indent.

Useful (Necessary for newbies to Docbook!!) Links

* [[http://wiki.gimp.org/ |Wiki Gimp Proposing advises in creating help file with Docbook]]
* [[http://docbook.org/ |Docbook Site]]
* [[http://www.nwalsh.com/ |Norman Walsh's WebSite, very complete about Docbook]]
* [[http://docbook.sourceforge.net/ |Tools for Docbook transformations]]
* [[http://i18n.kde.org/doc/markup/index.html |Advises for creating KDE compliant help files]]

Kwixson: *

2005-03-08T04:59:43Z

← Older revision		Revision as of 04:59, 8 March 2005
Line 14:		Line 14:
	* Refer to the terms defined at [[InkscapeTerminology \| Inkscape Terminology]]		* Refer to the terms defined at [[InkscapeTerminology \| Inkscape Terminology]]
	* Use good writing and documentation practices and maintain a neutral point of view		* Use good writing and documentation practices and maintain a neutral point of view
			* Write in a platform and hardware agnostic view, delineate differences where appropriate in a neutral way
	* Do not use first or second person pronouns, i.e, I, you, etc.		* Do not use first or second person pronouns, i.e, I, you, etc.
	* Refer to users as "Inkscape artists" or simply, "artists"		* Refer to users as "Inkscape artists" or simply, "artists"
	* Remain consistent in terminology		* Remain consistent in terminology
			* Keys on the keyboard are never "button" they are always "key"
			* The Control key should be written "Ctrl"
			* Key combinations should be written "Ctrl+Alt+Shift+<key>"
			* Tool names capitalize each word before "tool" but "tool" is not a proper noun and is not capitalized
			* A panel in the Document window is a "bar" (Tool Controls bar) and is not concatenated with the name, (i.e., "Status bar" not "Statusbar")
			* A "dialog" is a confirmation window, while other option dialogs are referred to as "window," and "window" is not capitalized
			* Refer to Menu selections with the ">" separator, a users "selects" a Menu "option" (or "command") and where possible include the keyboard shortcut in parentheses immediately after. For example: "...and then select Path>Object To Path (Shift+Ctrl+C) or if the..." It is not desirable to use the "/" character to denote levels of the Menu since / appears in the Menu and > does not. Capitalize each Menu option.

	Help file should be minimally structured to make it easy to use and comprehend. We propose that each page should be structured according to the base:		Help file should be minimally structured to make it easy to use and comprehend. We propose that each page should be structured according to the base:
Line 34:		Line 42:
	Help Structure		Help Structure

	The Manual should one unique big XML file, in which content can be separated in multiple included files by mean of entities. Each one of the included files will treat a unique point (a tool for example) and may have at least one link to access to it. Each one should also begin with the		The Manual should be one unique big XML file, in which content can be separated in multiple included files by mean of entities. Each one of the included files will treat a unique point (a tool for example) and may have at least one link to access to it. Each one should also begin with the

	<sect1>		<sect1>

Kwixson: *

2005-03-07T21:45:00Z

← Older revision		Revision as of 21:45, 7 March 2005
Line 1:		Line 1:
	INKSCAPE MANUAL : GUIDELINES FOR AUTHORS AND TRANSLATORS		== INKSCAPE MANUAL : GUIDELINES FOR AUTHORS AND TRANSLATORS ==
	~~Beginning~~

	~~'''STYLE GUIDE'''~~
			=== Style Guide ===

	This Manual of Style has the simple purpose of making things easy to read by following a consistent format — it is a style guide. The following rules don't claim to be the last word. One way is often as good as another, but if everyone does it the same way, user documentation will be easier to read and use, not to mention easier to write and edit. In this regard the following quote from The Chicago Manual of Style deserves notice:		This Manual of Style has the simple purpose of making things easy to read by following a consistent format — it is a style guide. The following rules don't claim to be the last word. One way is often as good as another, but if everyone does it the same way, user documentation will be easier to read and use, not to mention easier to write and edit. In this regard the following quote from The Chicago Manual of Style deserves notice:
Line 28:		Line 28:
	7. Links to other related pages		7. Links to other related pages

	~~'''DOCBOOK'''~~		=== DocBook ===

	We have decided to use, for good compliance, the most popular documentation system present in OpenSource. Help file may be written in Docbook (the XML one) format, that can be converted with different tools. For more informations, follow the links placed at the end of this page.		We have decided to use, for good compliance, the most popular documentation system present in OpenSource. Help file may be written in Docbook (the XML one) format, that can be converted with different tools. For more informations, follow the links placed at the end of this page.

Kwixson: *

2005-03-07T21:42:15Z

← Older revision		Revision as of 21:42, 7 March 2005
Line 13:		Line 13:

	* Refer to the terms defined at [[InkscapeTerminology \| Inkscape Terminology]]		* Refer to the terms defined at [[InkscapeTerminology \| Inkscape Terminology]]
	* Use good writing and ~~documentationpractices~~ and maintain a neutral point of view		* Use good writing and documentation practices and maintain a neutral point of view
	* Do not use first or second person pronouns, i.e, I, you, etc.		* Do not use first or second person pronouns, i.e, I, you, etc.
	* Refer to users as "Inkscape artists" or simply, "artists"		* Refer to users as "Inkscape artists" or simply, "artists"

Kwixson: *

2005-03-07T21:41:36Z

New page

INKSCAPE MANUAL : GUIDELINES FOR AUTHORS AND TRANSLATORS
Beginning

'''STYLE GUIDE'''

This Manual of Style has the simple purpose of making things easy to read by following a consistent format — it is a style guide. The following rules don't claim to be the last word. One way is often as good as another, but if everyone does it the same way, user documentation will be easier to read and use, not to mention easier to write and edit. In this regard the following quote from The Chicago Manual of Style deserves notice:

"Rules and regulations such as these, in the nature of the case, cannot be endowed
with the fixity of rock-ribbed law. They are meant for the average case, and must
be applied with a certain degree of elasticity."

(Above quoted from [http://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style Wikipedia:Manual Of Style])

* Refer to the terms defined at [[InkscapeTerminology | Inkscape Terminology]]
* Use good writing and documentationpractices and maintain a neutral point of view
* Do not use first or second person pronouns, i.e, I, you, etc.
* Refer to users as "Inkscape artists" or simply, "artists"
* Remain consistent in terminology

Help file should be minimally structured to make it easy to use and comprehend. We propose that each page should be structured according to the base:

1. Tool Name or Page Theme name
2. Image (screenshot of a dialog ...)
3. Methods for tool activation, eventually with step by step demonstration
4. Keydings, modifiers , eventually with step by step demonstration
5. Tool options, eventually with a screenshot of the Dialog, and , eventually with step by step demonstration
6. Additionnal Information
7. Links to other related pages

'''DOCBOOK'''

We have decided to use, for good compliance, the most popular documentation system present in OpenSource. Help file may be written in Docbook (the XML one) format, that can be converted with different tools. For more informations, follow the links placed at the end of this page.

Help Structure

The Manual should one unique big XML file, in which content can be separated in multiple included files by mean of entities. Each one of the included files will treat a unique point (a tool for example) and may have at least one link to access to it. Each one should also begin with the

<sect1>

root element to keep the hierarchy of the content. This root element can be changed into

<sect2>

in case of use of intermediate index (for example, some dialogs are full of options or manipulations advises that justify to have an index for its own).

Help file should be minimally structured to make it easy to use and comprehend. We propose that each page should be structured according to the base:

1. Tool Name or Page Theme name
2. Image (screenshot of a dialog ...)
3. Methods for tool activation, eventually with step by step demonstration
4. Keydings, modifiers , eventually with step by step demonstration
5. Tool options, eventually with a screenshot of the Dialog, and , eventually with step by step demonstration
6. Additionnal Information
7. Links to other related pages

DocBook Tags

Please, have a look at the Docbook Advice page and to the Websites listed below.

We also ask that contributors make a good use of indentation, in order to have more readable and useable source files.

1. Each tag containing visitor-readable-text should be placed on a new line with an additional indent;
2. Open and close tag of an element should be placed in the same indent.

Useful (Necessary for newbies to Docbook!!) Links

* [[http://wiki.gimp.org/ |Wiki Gimp Proposing advises in creating help file with Docbook]]
* [[http://docbook.org/ |Docbook Site]]
* [[http://www.nwalsh.com/ |Norman Walsh's WebSite, very complete about Docbook]]
* [[http://docbook.sourceforge.net/ |Tools for Docbook transformations]]
* [[http://i18n.kde.org/doc/markup/index.html |Advises for creating KDE compliant help files]]