mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-11-27 20:10:03 +00:00
Merge pull request #1359 from aelocson/doc-macros
Introduce documentation macros
This commit is contained in:
Jeremy Ruston
commit
d197af7995
@ -1,38 +0,0 @@
|
||||
created: 20141226192500000
|
||||
title: Instruction Tiddlers
|
||||
tags: documenting
|
||||
|
||||
Instruction tiddlers talk directly to the reader and guide them through a process. The reader is likely to be a beginner or an intermediate user.
|
||||
|
||||
Such tiddlers can be subcategorised as:
|
||||
|
||||
* ''Welcome''
|
||||
** What is ~TiddlyWiki and why should I care?
|
||||
** Demonstrations of key features and benefits
|
||||
** Frequently asked questions
|
||||
** Examples of ~TiddlyWiki in the field
|
||||
** Information about the project itself
|
||||
|
||||
* ''Tutorial''
|
||||
** An ordered presentation of material for beginners
|
||||
** Each tiddler introduces one new point or concept
|
||||
** Its main content contains very few links
|
||||
** A revealable "Further reading" section at the end can offer related links
|
||||
|
||||
* ''Exercise''
|
||||
** Accompanying a tutorial tiddler
|
||||
** Solution revealed on demand
|
||||
|
||||
* ''How-to''
|
||||
** A list of numbered steps for performing a small specific task
|
||||
** Concise, with links to reference tiddlers where appropriate
|
||||
** Often has a preamble to clarify the nature of the task
|
||||
|
||||
* ''Example''
|
||||
** Accompanying a [[Reference Tiddler|Reference Tiddlers]]
|
||||
** Can contain explanations and similar commentary
|
||||
** Kept separate to keep the reference tiddler pure
|
||||
|
||||
Instruction tiddlers talk directly to the reader as "you". They can be reasonably chatty.
|
||||
|
||||
But they avoid excessively colloquial language, cultural or topical references and attempts at humour, as these can baffle or even offend the international readership. They also avoid potentially frustrating the reader with descriptions of features as "convenient" or "easy".
|
||||
@ -1,25 +0,0 @@
|
||||
created: 20141226192500000
|
||||
title: Reference Tiddlers
|
||||
tags: documenting
|
||||
|
||||
Reference tiddlers offer raw information in a comprehensive interlinked way. The reader is likely to be an intermediate or expert user.
|
||||
|
||||
There are several subcategories:
|
||||
|
||||
* ''Concepts''
|
||||
** With definitions, together forming a glossary
|
||||
* ''User manual''
|
||||
** Presenting technical details of ~WikiText features
|
||||
** Subcategorised: messages, operators, widgets, etc
|
||||
* ''Developer manual''
|
||||
** Presenting technical details of ~TiddlyWiki's internal architecture
|
||||
|
||||
Reference material is written in a terse, formal style that avoids referring to the reader, and instead focuses on how ~TiddlyWiki itself behaves. The passive voice is often suitable:
|
||||
|
||||
* "the template can be specified as a tiddler" rather than "specify the template as a tiddler"
|
||||
* "the widget can be used for various purposes" rather than "you can use the widget for various purposes"
|
||||
* But "this widget has several possible uses" is better, because it is more succinct
|
||||
|
||||
Contracted verb forms are normally avoided in reference tiddlers.
|
||||
|
||||
To reduce the risk that the reader will overlook the word "not", it can be italicised.
|
||||
@ -1,13 +0,0 @@
|
||||
created: 20141226192500000
|
||||
title: Tiddler Titles
|
||||
tags: documenting
|
||||
|
||||
Each of the main words of a tiddler title begins with a capital letter, but minor words such as "and", "or", "the", "to" and "with" do not. Avoid starting a tiddler with the word "the".
|
||||
|
||||
[[Reference Tiddlers]] have ~CamelCase nouns as their titles, e.g. ''~RevealWidget'', ''~CamelCase'', ''CSS''. The title is plural if it denotes a category, e.g. ''~KeyboardShortcuts'', ''~TiddlerFields''. Such categories are used to tag more specific tiddlers within the category.
|
||||
|
||||
Other tags usually consist of a single lowercase word. Avoid spaces in tags.
|
||||
|
||||
[[Instruction Tiddlers]] have spaces between the words of their titles. Each word that contributes significantly to the meaning of the title starts with a capital letter. Words that are little more than structural signposts ("the", "and", "of", etc) are entirely lowercase.
|
||||
|
||||
How-to tiddlers have titles that begin with ''How to''.
|
||||
@ -1,26 +0,0 @@
|
||||
created: 20141226192500000
|
||||
title: Typography
|
||||
tags: documenting
|
||||
|
||||
Use ''bold'' when referring to:
|
||||
|
||||
* Captions in ~TiddlyWiki's user interface:
|
||||
** "the ''Recent'' tab", "the ''Hide sidebar'' button"
|
||||
* Tiddler fields:
|
||||
** "the ''list'' field"
|
||||
* Example tiddlers and tags:
|
||||
** "create a tiddler called ''Super Soup Recipe'' with the tag ''cookery''"
|
||||
|
||||
''Bold'' is also used to make part or all of a sentence stand out from the rest of the tiddler.
|
||||
|
||||
Use //italics// to give more subtle emphasis to a word or phrase.
|
||||
|
||||
Use `monospaced` text when a sentence contains a fragment of ~WikiText or a string that the user could type.
|
||||
|
||||
Use the double quotation mark `"` as the basic one. It is easier to read on screen, and it avoids confusion with the apostrophe. To keep things clean and simple, quotation marks and apostrophes should be straight `'`, not curly `’`, and the ellipsis should be three separate dots `...` rather than `…`
|
||||
|
||||
Avoid using a single hyphen `-` as sentence punctuation. Instead, use a double hyphen -- which ~TiddlyWiki renders as an en-dash -- with a space on either side.
|
||||
|
||||
Items in lists and tables should only end with a full stop (period in US English) if they are complete sentences. They should have no trailing punctuation otherwise.
|
||||
|
||||
It is very rarely necessary to use an exclamation mark in professional documentation.
|
||||
140
editions/tw5.com/tiddlers/styleguide/Documentation Macros.tid
Normal file
140
editions/tw5.com/tiddlers/styleguide/Documentation Macros.tid
Normal file
@ -0,0 +1,140 @@
|
||||
created: 20150110182600000
|
||||
title: Documentation Macros
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
The following macros are used throughout the documentation.
|
||||
|
||||
!General
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|doc-def |the defining instance of a term |<<doc-def widget>> |
|
||||
|doc-em |minor emphasis within a sentence |<<doc-em not>> |
|
||||
|doc-ph |a placeholder for the user to fill in |<<doc-ph tagname>> |
|
||||
|doc-strong |major emphasis within a tiddler |<<doc-strong Important!>> |
|
||||
|doc-w |a mention of an ordinary word or phrase |<<doc-w "hello world">> |
|
||||
|
||||
!Tiddlers and fields
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|doc-tiddler |a tiddler title|<<doc-tiddler Example>> |
|
||||
|doc-tag |a tag |<<doc-tag Example>> |
|
||||
|doc-field|a field name|<<doc-field example>> |
|
||||
|doc-field-value|a field value|<<doc-field-value "example value">> |
|
||||
|doc-var|a variable or macro name|<<doc-var currentTiddler>> |
|
||||
|doc-widget|a widget name|<<doc-widget list>> |
|
||||
|
||||
!Links
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|doc-link |a link containing WikiText |<<doc-link "^^an^^ ~~example~~" Example>> |
|
||||
|doc-clink |a code link |<<doc-clink `<$list>` ListWidget>> |
|
||||
|
||||
!User interface
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|doc-key |a key on the keyboard |<<doc-key Escape>> |
|
||||
|doc-key-combo |a key combination |<<doc-key-combo Ctrl Enter>> |
|
||||
|doc-input |text entered by the user |<<doc-input "npm install -g tiddlywiki">> |
|
||||
|doc-output |text output by the system |<<doc-output "Serving on 127.0.0.1:8080">> |
|
||||
|
||||
!Tabs
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|doc-sidebar-tab |the name of a sidebar tab |<<doc-sidebar-tab More>> |
|
||||
|doc-more-tab |the name of a subtab of the More tab |<<doc-more-tab Shadows>> |
|
||||
|doc-info-tab |the name of a tiddler info tab |<<doc-info-tab Fields>> |
|
||||
|doc-controlpanel-tab |the name of a Control Panel tab |<<doc-controlpanel-tab Settings>> |
|
||||
|doc-advancedsearch-tab |the name of an Advanced Search tab |<<doc-advancedsearch-tab Filter>> |
|
||||
|doc-toc-tab |name of the tw5.com TOC tab |<<doc-toc-tab>> |
|
||||
|doc-example-tab |an example tab name |<<doc-example-tab "Notes">> |
|
||||
|
||||
!!Parameters for doc-sidebar-tab
|
||||
|
||||
|Open |<<doc-sidebar-tab Open>> |
|
||||
|Recent |<<doc-sidebar-tab Recent>> |
|
||||
|Tools |<<doc-sidebar-tab Tools>> |
|
||||
|More |<<doc-sidebar-tab More>> |
|
||||
|
||||
!!Parameters for doc-more-tab
|
||||
|
||||
|All |<<doc-more-tab All>> |
|
||||
|Recent |<<doc-more-tab Recent>> |
|
||||
|Tags |<<doc-more-tab Tags>> |
|
||||
|Missing |<<doc-more-tab Missing>> |
|
||||
|Drafts |<<doc-more-tab Drafts>> |
|
||||
|Orphans |<<doc-more-tab Orphans>> |
|
||||
|Types |<<doc-more-tab Types>> |
|
||||
|System |<<doc-more-tab System>> |
|
||||
|Shadows |<<doc-more-tab Shadows>> |
|
||||
|
||||
!!Parameters for doc-info-tab
|
||||
|
||||
|Tools |<<doc-info-tab Tools>> |
|
||||
|References |<<doc-info-tab References>> |
|
||||
|Tagging |<<doc-info-tab Tagging>> |
|
||||
|List |<<doc-info-tab List>> |
|
||||
|Listed |<<doc-info-tab Listed>> |
|
||||
|Fields |<<doc-info-tab Fields>> |
|
||||
|Advanced |<<doc-info-tab Advanced>> |
|
||||
|
||||
!!Parameters for doc-controlpanel-tab
|
||||
|
||||
|Info |<<doc-controlpanel-tab Info>> |
|
||||
|Appearance |<<doc-controlpanel-tab Appearance>> |
|
||||
|Settings |<<doc-controlpanel-tab Settings>> |
|
||||
|Saving |<<doc-controlpanel-tab Saving>> |
|
||||
|Plugins |<<doc-controlpanel-tab Plugins>> |
|
||||
|
||||
!!Parameters for doc-advancedsearch-tab
|
||||
|
||||
|Standard |<<doc-advancedsearch-tab Standard>> |
|
||||
|System |<<doc-advancedsearch-tab System>> |
|
||||
|Shadows |<<doc-advancedsearch-tab Shadows>> |
|
||||
|Filter |<<doc-advancedsearch-tab Filter>> |
|
||||
|
||||
!Buttons
|
||||
|
||||
|!Macro |!Used for |!Example |
|
||||
|doc-button |a standard button name and icon |<<doc-button "new-tiddler">> |
|
||||
|
||||
!!Parameters for doc-button
|
||||
|
||||
!!!Tiddler toolbar
|
||||
|
||||
|clone |<<doc-button "clone">> |
|
||||
|close |<<doc-button "close">> |
|
||||
|close-others |<<doc-button "close-others">> |
|
||||
|edit |<<doc-button "edit">> |
|
||||
|export-tiddler |<<doc-button "export-tiddler">> |
|
||||
|info |<<doc-button "info">> |
|
||||
|more-tiddler-actions |<<doc-button "more-tiddler-actions">> |
|
||||
|new-here |<<doc-button "new-here">> |
|
||||
|new-journal-here |<<doc-button "new-journal-here">> |
|
||||
|permalink |<<doc-button "permalink">> |
|
||||
|
||||
!!!Edit-mode toolbar
|
||||
|
||||
|cancel |<<doc-button "cancel">> |
|
||||
|delete |<<doc-button "delete">> |
|
||||
|save |<<doc-button "save">> |
|
||||
|
||||
!!!Page toolbar
|
||||
|
||||
|advanced-search |<<doc-button "advanced-search">> |
|
||||
|close-all |<<doc-button "close-all">> |
|
||||
|control-panel |<<doc-button "control-panel">> |
|
||||
|encryption |<<doc-button "encryption">> |
|
||||
|export-page |<<doc-button "export-page">> |
|
||||
|full-screen |<<doc-button "full-screen">> |
|
||||
|home |<<doc-button "home">> |
|
||||
|import |<<doc-button "import">> |
|
||||
|language |<<doc-button "language">> |
|
||||
|more-page-actions |<<doc-button "more-page-actions">> |
|
||||
|new-journal |<<doc-button "new-journal">> |
|
||||
|new-tiddler |<<doc-button "new-tiddler">> |
|
||||
|permaview |<<doc-button "permaview">> |
|
||||
|refresh |<<doc-button "refresh">> |
|
||||
|save-wiki |<<doc-button "save-wiki">> |
|
||||
|storyview |<<doc-button "storyview">> |
|
||||
|tag-manager |<<doc-button "tag-manager">> |
|
||||
|theme |<<doc-button "theme">> |
|
||||
@ -1,7 +1,7 @@
|
||||
created: 20140904164608166
|
||||
modified: 20140904164935351
|
||||
modified: 20150110181800000
|
||||
title: Documentation Style Guide
|
||||
tags: documenting [[Improving TiddlyWiki Documentation]]
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
The documentation for ~TiddlyWiki tries to follow a consistent editorial style. It has two main areas, each with its own tone and audience:
|
||||
@ -9,10 +9,13 @@ The documentation for ~TiddlyWiki tries to follow a consistent editorial style.
|
||||
* [[Instruction Tiddlers]]
|
||||
* [[Reference Tiddlers]]
|
||||
|
||||
Keep the two areas distinct, otherwise beginners will be overwhelmed and experts will be denied quick access to information.
|
||||
We keep the two areas distinct. This avoids overwhelming relative newcomers, while still providing quick access to the information that expert users need.
|
||||
|
||||
* [[Tiddler Titles]]
|
||||
Additional topics:
|
||||
|
||||
* [[Tiddler Title Policy]]
|
||||
* [[Tiddler Structure]]
|
||||
* [[Spelling]]
|
||||
* [[Typography]]
|
||||
* [[Technical Prose Style]]
|
||||
* [[Documentation Macros]]
|
||||
* [[Technical Prose Style]]
|
||||
@ -0,0 +1,39 @@
|
||||
created: 20150110101500000
|
||||
modified: 20150110181800000
|
||||
title: Instruction Tiddlers
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
<<doc-def "Instruction tiddlers">> talk directly to the reader and guide them through a process. The reader is likely to be a beginner or an intermediate user.
|
||||
|
||||
Such tiddlers can be subcategorised as:
|
||||
|
||||
;Welcome
|
||||
* What is ~TiddlyWiki and why should I care?
|
||||
* Demonstrations of key features and benefits
|
||||
* Frequently asked questions
|
||||
* Examples of ~TiddlyWiki in the field
|
||||
* Information about the project itself
|
||||
|
||||
;Tutorial
|
||||
* An ordered presentation of material for beginners
|
||||
* Each tiddler introduces one new point or concept
|
||||
* Its main content contains very few links
|
||||
* A revealable <<doc-w "Find out more">> section at the end can offer related links
|
||||
|
||||
;Exercise
|
||||
* Accompanying a tutorial tiddler
|
||||
* Solution revealed on demand
|
||||
|
||||
;How-to
|
||||
* A list of numbered steps for performing a small specific task
|
||||
* Concise, with links to reference tiddlers where appropriate
|
||||
* Often has a preamble to clarify the nature of the task
|
||||
|
||||
;Example
|
||||
* Accompanying a [[reference tiddler|Reference Tiddlers]]
|
||||
* Can contain explanations and similar commentary
|
||||
* Kept separate to keep the reference tiddler pure
|
||||
|
||||
Instruction tiddlers talk directly to the reader as <<doc-w you>>. They can be reasonably chatty.
|
||||
|
||||
But they avoid excessively colloquial language, cultural or topical references and attempts at humour, as these can baffle or even offend the international readership. They also avoid potentially frustrating the reader with descriptions of features as <<doc-w convenient>> or <<doc-w easy>>.
|
||||
26
editions/tw5.com/tiddlers/styleguide/Reference Tiddlers.tid
Normal file
26
editions/tw5.com/tiddlers/styleguide/Reference Tiddlers.tid
Normal file
@ -0,0 +1,26 @@
|
||||
created: 20141226192500000
|
||||
modified: 20150110182100000
|
||||
title: Reference Tiddlers
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
<<doc-def "Reference tiddlers">> offer raw information in a comprehensive interlinked way. The reader is likely to be an intermediate or expert user.
|
||||
|
||||
There are several subcategories:
|
||||
|
||||
;Concepts
|
||||
* With definitions, together forming a glossary
|
||||
|
||||
;User manual
|
||||
* Presenting technical details of ~WikiText features
|
||||
* Subcategorised: messages, operators, widgets, etc
|
||||
|
||||
;Developer manual
|
||||
* Presenting technical details of ~TiddlyWiki's internal architecture
|
||||
|
||||
Reference material is written in a terse, formal style that avoids referring to the reader, and instead focuses on how ~TiddlyWiki itself behaves. The passive voice is often suitable:
|
||||
|
||||
* <<doc-w "the template is specified as a tiddler">> rather than <<doc-w "specify the template as a tiddler">>
|
||||
* <<doc-w "the widget can be used for various purposes">> rather than <<doc-w "you can use the widget for various purposes">>
|
||||
* But <<doc-w "this widget has several possible uses">> is better, because it is less convoluted and more succinct
|
||||
|
||||
Most contracted verb forms are avoided in reference tiddlers. But those ending in <<doc-w "n't">> (<<doc-w "aren't">>, <<doc-w "doesn't">>, <<doc-w "hasn't">>, <<doc-w "isn't">>, etc) are acceptable, as they make it less easy to accidentally overlook the word <<doc-w not>>.
|
||||
@ -1,12 +1,12 @@
|
||||
created: 20141226192500000
|
||||
created: 20150110182900000
|
||||
title: Spelling
|
||||
tags: documenting
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
Because ~TiddlyWiki is of British origin, its English documentation uses [[British spelling in preference to US spelling|http://en.wikipedia.org/wiki/American_and_British_English_spelling_differences]].
|
||||
|
||||
Words like "customise" are spelled "-ise", not "-ize".
|
||||
Words like <<doc-w customise>> are spelled <<doc-w -ise>>, not <<doc-w -ize>>.
|
||||
|
||||
Standard technical acronyms are written in upper case, without dots: `HTML`, not `html` or `H.T.M.L.`
|
||||
Standard technical acronyms are written in upper case, without dots: <<doc-w HTML>>, not <<doc-w html>> or <<doc-w H.T.M.L.>>
|
||||
|
||||
Avoid arbitrarily abbreviating words and sentences. But the following abbreviations are acceptable:
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
created: 20141226192500000
|
||||
created: 20150110182900000
|
||||
title: Technical Prose Style
|
||||
tags: documenting
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
When writing an [[Instruction Tiddler|Instruction Tiddlers]], start by planning a route through the information you wish to present. This should be a simple, logical, direct progression of thoughts, with no backtracking or forward references. Use this approach even within individual sentences: always proceed from cause to effect, from the old or known to the new or unknown.
|
||||
When writing an [[instruction tiddler|Instruction Tiddlers]], start by planning a route through the information you wish to present. This should be a simple, logical, direct progression of thoughts, with no backtracking or forward references. Use this approach even within individual sentences: always proceed from cause to effect, from the old or known to the new or unknown.
|
||||
|
||||
Keep sentences short and simple. A clear technical sentence seldom contains more than one idea. It therefore avoids parenthetical information. Similarly, keep paragraph structure simple. A flat presentation is often easier to understand than a hierarchical one.
|
||||
|
||||
It is often possible to simplify a sentence without changing its meaning merely by adjusting its vocabulary. "Execution of the macro is performed" just means "The macro runs". "Your expectation might be..." just means "You might expect..."
|
||||
It is often possible to simplify a sentence without changing its meaning merely by adjusting its vocabulary. <<doc-w "Execution of the macro is performed">> just means <<doc-w "The macro runs">>. <<doc-w "Your expectation might be...">> just means <<doc-w "You might expect...">>.
|
||||
|
||||
Prefer the active voice by default: "Jane creates a tiddler" rather than "a tiddler is created by Jane". The passive voice can be useful if you want the reader to focus on the action itself or its result: "a tiddler is created". But it may be clearer to proceed from cause to effect and say "this creates a tiddler" in the active voice.
|
||||
Prefer the active voice by default: <<doc-w "Jane creates a tiddler">> rather than <<doc-w "a tiddler is created by Jane">>. The passive voice can be useful if you want the reader to focus on the action itself or its result: <<doc-w "a tiddler is created">>. But it may be clearer to proceed from cause to effect and say <<doc-w "this creates a tiddler">> in the active voice.
|
||||
|
||||
Documentation often presents two items that are parallel either by similarity or by difference. The reader will more easily detect such a pattern if you use the same sentence or phrase structure for both. But this must be balanced with the need to avoid monotony.
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
created: 20141226192500000
|
||||
created: 20150110183300000
|
||||
title: Tiddler Structure
|
||||
tags: documenting
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
In accordance with the [[Philosophy of Tiddlers]], documentation tiddlers are typically short and interlinked.
|
||||
|
||||
When a tiddler seems as if it needs to contain subheadings, this is often a sign that it should in fact be split into several tiddlers. But it is reasonable for a [[Reference Tiddler|Reference Tiddlers]] to consist of an untitled introductory section followed by a titled section of details.
|
||||
When a tiddler seems as if it needs to contain subheadings, this is often a sign that it should in fact be split into several tiddlers. But it is reasonable for a [[reference tiddler|Reference Tiddlers]] to consist of an untitled introductory section followed by a titled section of details.
|
||||
|
||||
Consistency of terminology is essential if the reader is not to become confused. Consistent typography and punctuation lend a professional quality to the documentation. Macros can improve the consistency and maintainability of the text.
|
||||
|
||||
Use numbered lists for step-by-step instructions, and bullet points for lists whose order is arbitrary. Use a definition list in preference to a bulleted list if each bulleted item would begin with a term and a colon. If at all possible, avoid burdening the reader with a nested list.
|
||||
|
||||
Use a table when information naturally falls into three or more columns, and also for lists of parameters, attributes, etc in [[Reference Tiddlers]].
|
||||
Use a table when information naturally falls into three or more columns, and also for lists of parameters, attributes, etc in [[reference tiddlers|Reference Tiddlers]].
|
||||
|
||||
The documentation describes the current reality of ~TiddlyWiki. Avoid discussing future aspirations.
|
||||
@ -0,0 +1,22 @@
|
||||
created: 20150110183300000
|
||||
modified: 20150110190400000
|
||||
title: Tiddler Title Policy
|
||||
tags: [[Improving TiddlyWiki Documentation]]
|
||||
|
||||
Many documentation tiddlers, especially the [[reference ones|Reference Tiddlers]], are concerned with a single concept. Their titles should be succinct noun phrases like <<doc-tiddler "List Widget">> or <<doc-tiddler "Tiddler Fields">>.
|
||||
|
||||
Each of the main words of such a title begins with a capital letter. Minor words such as <<doc-w and>>, <<doc-w or>>, <<doc-w the>>, <<doc-w to>> and <<doc-w with>> do not.
|
||||
|
||||
Tags also follow this pattern.
|
||||
|
||||
Titles of this kind are plural if they denote a category of items, e.g. <<doc-tiddler "Keyboard Shortcuts">> or <<doc-tiddler "Tiddler Fields">>. Such titles are used to tag more specific tiddlers within the category.
|
||||
|
||||
Where a concept is an item rather than a category, its tiddler has a singular title, e.g. <<doc-tiddler "List Widget">>, <<doc-tiddler "Tag Operator">>.
|
||||
|
||||
Avoid starting a title with the word <<doc-w the>>.
|
||||
|
||||
In the past, many tiddlers had CamelCase titles. This is gradually being phased out of the documentation to improve readability. ~CamelCase titles should no longer be used, even for tags, except in cases like <<doc-tiddler ~JavaScript>> where that is the standard spelling.
|
||||
|
||||
[[Instruction tiddlers|Instruction Tiddlers]] often have longer titles that can be more complicated than just a noun phrase, e.g. <<doc-tiddler "Ten reasons to switch to ~TiddlyWiki">> These titles use sentence case, i.e. only the first word (and any proper names) starts with a capital letter.
|
||||
|
||||
How-to tiddlers have titles that begin with <<doc-w "How to">>, e.g. <<doc-tiddler "How to edit a tiddler">>. Avoid titles like <<doc-tiddler "Editing tiddlers">>, because a less fluent English speaker could misunderstand that as the name of a category of tiddlers.
|
||||
19
editions/tw5.com/tiddlers/styleguide/Typography.tid
Normal file
19
editions/tw5.com/tiddlers/styleguide/Typography.tid
Normal file
@ -0,0 +1,19 @@
|
||||
created: 20141226192500000
|
||||
title: Typography
|
||||
tags: documenting
|
||||
|
||||
Use the [[documentation macros|Documentation Macros]] to keep the text maintainable in the face of change.
|
||||
|
||||
Be wary of arbitrarily applying raw bold or italic markup in a sentence. If there's a suitable macro, use that instead. If there isn't a suitable macro, write one or request one.
|
||||
|
||||
Use simple backticks (<code>`...`</code>) for fragments of WikiText.
|
||||
|
||||
To keep things clean and simple, quotation marks and apostrophes should be straight `'`, not curly `’`, and the ellipsis should be three separate dots `...` rather than `…`.
|
||||
|
||||
Use `"` as the primary quotation mark, reserving `'` for the rare case of a nested quotation.
|
||||
|
||||
Avoid using a single hyphen `-` as sentence punctuation. Instead, use a double hyphen -- which ~TiddlyWiki renders as an en-dash -- with a space on either side.
|
||||
|
||||
Items in lists and tables should only end with a full stop (period in US English) if they are complete sentences. They should have no trailing punctuation otherwise.
|
||||
|
||||
It is very rarely necessary to use an exclamation mark in professional documentation.
|
||||
38
editions/tw5.com/tiddlers/system/doc-macros.tid
Normal file
38
editions/tw5.com/tiddlers/system/doc-macros.tid
Normal file
@ -0,0 +1,38 @@
|
||||
title: $:/editions/tw5.com/doc-macros
|
||||
tags: $:/tags/Macro
|
||||
|
||||
\define doc-if(cond,then,else) <$reveal type="nomatch" default="$cond$" text="">$then$</$reveal><$reveal type="match" default="$cond$" text="">$else$</$reveal>
|
||||
|
||||
\define doc-def(_) <dfn class="doc-def">$_$</dfn>
|
||||
\define doc-em(_) <em class="doc-em">$_$</em>
|
||||
\define doc-strong(_) <strong class="doc-strong">$_$</strong>
|
||||
\define doc-ph(_) <var class="doc-ph">$_$</var>
|
||||
\define doc-w(_) "$_$"
|
||||
|
||||
\define doc-tiddler(_) <code class="doc-tiddler">$_$</code>
|
||||
\define doc-tag(_) <code class="doc-tag">$_$</code>
|
||||
\define doc-field(_) <code class="doc-field">$_$</code>
|
||||
\define doc-field-value(_) <code class="doc-field-value">$_$</code>
|
||||
\define doc-var(_) <code class="doc-var">$_$</code>
|
||||
\define doc-widget(_) <code class="doc-widget">$_$</code>
|
||||
|
||||
\define doc-link(_,to) <$link to="$to$">$_$</$link>
|
||||
\define doc-clink(_,to) <span class="doc-clink"><<doc-link """$_$""" "$to$">></span>
|
||||
|
||||
\define doc-key(_) <span class="doc-key">$_$</span>
|
||||
\define doc-combo-key(_) <$macrocall $name="doc-if" cond="$_$" then="<<doc-key '$_$'>>"/>
|
||||
\define doc-key-combo(1,2,3,4) <<doc-combo-key "$1$">><<doc-if "$2$" +>><<doc-combo-key "$2$">><<doc-if "$3$" +>><<doc-combo-key "$3$">><<doc-if "$4$" +>><<doc-combo-key "$4$">>
|
||||
|
||||
\define doc-input(_) `$_$`
|
||||
\define doc-output(_) `$_$`
|
||||
|
||||
\define doc-tab(_) <span class="doc-tab">{{$_$!!caption}}</span>
|
||||
\define doc-sidebar-tab(_) <<doc-tab "$:/core/ui/SideBar/$_$">>
|
||||
\define doc-more-tab(_) <<doc-tab "$:/core/ui/MoreSideBar/$_$">>
|
||||
\define doc-info-tab(_) <<doc-tab "$:/core/ui/TiddlerInfo/$_$">>
|
||||
\define doc-controlpanel-tab(_) <<doc-tab "$:/core/ui/ControlPanel/$_$">>
|
||||
\define doc-advancedsearch-tab(_) <<doc-tab "$:/core/ui/AdvancedSearch/$_$">>
|
||||
\define doc-toc-tab() <<doc-tab "TableOfContents">>
|
||||
\define doc-example-tab(_) <span class="doc-tab">$_$</span>
|
||||
|
||||
\define doc-button(_) <span class="doc-button">{{$:/core/ui/Buttons/$_$!!caption}}</span>
|
||||
57
editions/tw5.com/tiddlers/system/doc-styles.tid
Normal file
57
editions/tw5.com/tiddlers/system/doc-styles.tid
Normal file
@ -0,0 +1,57 @@
|
||||
title: $:/editions/tw5.com/doc-styles
|
||||
tags: $:/tags/Stylesheet
|
||||
|
||||
.doc-def {
|
||||
font-style: normal;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.doc-em {
|
||||
font-style: italic;
|
||||
font-variant: small-caps;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.doc-strong {
|
||||
color: <<colour alert-highlight>>;
|
||||
font-style: normal;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.doc-foreign {
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
.doc-ph {
|
||||
border: none;
|
||||
color: <<color foreground>>;
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
.doc-button,
|
||||
.doc-tab,
|
||||
.doc-tag,
|
||||
.doc-tiddler,
|
||||
.doc-field,
|
||||
.doc-field-value,
|
||||
.doc-var,
|
||||
.doc-widget {
|
||||
background: <<color background>>;
|
||||
border: none;
|
||||
color: <<color very-muted-foreground>>;
|
||||
font-weight: bold;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.doc-button svg {
|
||||
height: 1em;
|
||||
}
|
||||
|
||||
.doc-key {
|
||||
color: <<color very-muted-foreground>>;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.doc-clink code {
|
||||
color: <<colour tiddler-link-foreground>>;
|
||||
}
|
||||
Loading…
Reference in New Issue
Block a user