mirror of
https://gitlab.com/openlp/documentation.git
synced 2024-09-29 19:37:43 +00:00
192 lines
4.4 KiB
ReStructuredText
192 lines
4.4 KiB
ReStructuredText
|
style_guide.rst
|
||
|
=========================
|
||
|
OpenLP Manual Style Guide
|
||
|
=========================
|
||
|
|
||
|
This Style Guide will be used to clarify how the manual is formated and is
|
||
|
intended to keep all the pages in the manual consistent.
|
||
|
|
||
|
Page Title
|
||
|
==========
|
||
|
|
||
|
Each page will begine with a link reference and a title. The link reference
|
||
|
should be the same as the title except that it is all in lower case with no
|
||
|
spaces. Titles are to be in Title Case.
|
||
|
|
||
|
Example:
|
||
|
--------
|
||
|
|
||
|
.. _bibles:
|
||
|
|
||
|
======
|
||
|
Bibles
|
||
|
======
|
||
|
|
||
|
end example
|
||
|
|
||
|
Line Length
|
||
|
===========
|
||
|
|
||
|
Each line of the document should be no longer than 80 charectors. While
|
||
|
the build system can wrap the text, lines longer than 80 charectors can cause
|
||
|
unwelcome results.
|
||
|
|
||
|
Pictures
|
||
|
========
|
||
|
|
||
|
All pictures used in the page will be described at the end of the document and
|
||
|
image pointers will be used inside the document when an image is to be
|
||
|
displayed. The image deffinition uses upper case for the image title and the
|
||
|
in line image link uses lower case for the image title. No spaces are to be
|
||
|
used in the image deffinition title. The image deffinition title will start
|
||
|
with the page name unless the image is used across pages.
|
||
|
|
||
|
End of Page Example:
|
||
|
--------------------
|
||
|
|
||
|
.. pictures used in this page
|
||
|
|
||
|
.. |DELETEICON| image:: pics/theme_delete.png
|
||
|
|
||
|
In Page Example:
|
||
|
--------------------
|
||
|
|
||
|
Click on the |deleteicon| Delete Icon to delete the Bible.
|
||
|
|
||
|
end of examples
|
||
|
|
||
|
On Screen Buttons
|
||
|
=================
|
||
|
|
||
|
When instructing the user to use an on screen button, use the Gui label formated
|
||
|
to make the button stand out.
|
||
|
|
||
|
Gui Label Format :guilabel:`Next`
|
||
|
|
||
|
Menu Paths
|
||
|
==========
|
||
|
|
||
|
When describing a menu path, use the menu selection format.
|
||
|
|
||
|
:menuselection:`File --> Import --> Bible`
|
||
|
|
||
|
Referance Links For Headers
|
||
|
===========================
|
||
|
|
||
|
All sublevel headers will have a referance link above the header.
|
||
|
The referance link name will start with the page title and then the sublevel
|
||
|
title. No spaces are allowed in the link reference.
|
||
|
|
||
|
Example:
|
||
|
--------
|
||
|
|
||
|
.. _bibles_sublevel:
|
||
|
|
||
|
Sublevel
|
||
|
========
|
||
|
|
||
|
end of example
|
||
|
|
||
|
Terminal Commands
|
||
|
=================
|
||
|
|
||
|
When telling the user to enter a command on the command prompt or in a terminal
|
||
|
window, use a double colon and 1 blank line before what the user is to type.
|
||
|
Add 1 blank line after the what the user is to type.
|
||
|
|
||
|
Example:
|
||
|
--------
|
||
|
|
||
|
To convert a Bible using the command prompt in
|
||
|
Windows or a terminal in Linux or macOS you would type:
|
||
|
|
||
|
mod2osis biblename > biblename.osis
|
||
|
|
||
|
end of example
|
||
|
|
||
|
Codeing
|
||
|
=======
|
||
|
|
||
|
When entering coding use the wrap the coding inside two ` characters.
|
||
|
|
||
|
Example:
|
||
|
--------
|
||
|
|
||
|
``<div align="left">``
|
||
|
|
||
|
end of example
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
so if you're going through and listing each and every action in that toolbar, then use this style: http://manual.openlp.org/mediamanager.html#toolbar
|
||
|
[20:57] <superfly> But if you're documenting a feature, and you want to include an icon, you should make it an inline icon.
|
||
|
[20:57] <JohnMFL> superfly: so if it is a one liner, then use the toolbar formatting and if we have to explain what to do when you
|
||
|
push the icon then use the inline
|
||
|
|
||
|
Development:String Standards
|
||
|
|
||
|
Definitions
|
||
|
===========
|
||
|
|
||
|
Sentence case
|
||
|
+++++++++++++
|
||
|
|
||
|
The first letter of the first word is upper case, all other letters are lower case, unless the word is a proper noun.
|
||
|
|
||
|
Title case
|
||
|
++++++++++
|
||
|
The first letter of all words is upper case, except for secondary 2 letter words ("Go to Next Slide").
|
||
|
|
||
|
Names of Widgets
|
||
|
++++++++++++++++
|
||
|
All widget names should be normal parts of sentences, e.g. "Cannot drag item from media manager to service manager."
|
||
|
|
||
|
Standards
|
||
|
=========
|
||
|
|
||
|
Labels
|
||
|
++++++
|
||
|
|
||
|
All labels should be sentence case and end with a colon, unless the label is attached to check box or radio button: "Select theme file:"
|
||
|
|
||
|
Group Box Labels
|
||
|
++++++++++++++++
|
||
|
|
||
|
Group box labels should be title case, without any trailing colons: "Display Options"
|
||
|
|
||
|
Menu Items
|
||
|
++++++++++
|
||
|
|
||
|
Menu items should be title case: "Go to Next Slide", "Save As"
|
||
|
|
||
|
Window/Dialog Titles
|
||
|
++++++++++++++++++++
|
||
|
|
||
|
All window and dialog titles should be title case: "Open Service File"
|
||
|
|
||
|
Dialog Text
|
||
|
+++++++++++
|
||
|
|
||
|
Dialog text must be full, proper sentences, with each sentence ending in a period.
|
||
|
|
||
|
Tooltips (hints)
|
||
|
++++++++++++++++
|
||
|
|
||
|
Tooltips should be sentence case, and end with a period: "Open an existing service file."
|
||
|
|
||
|
Combo Boxes
|
||
|
+++++++++++
|
||
|
|
||
|
Data in combo boxes should be in title case: "New International Version"
|
||
|
|
||
|
Check Boxes
|
||
|
+++++++++++
|
||
|
|
||
|
Check boxes should have sentence case labels.
|
||
|
|
||
|
Buttons
|
||
|
+++++++
|
||
|
|
||
|
Buttons should have title case labels.
|