documentation/style_guide.rst

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.

.. _bibles:

======
Bibles
======

Line Length

Each line of the document should be no longer than 120 characters. While the build system can wrap the text, lines longer than 120 characters are difficult to manage in a text editor.

Pictures

All pictures will be in the .png format and stored in the pics directory of the manual. If the pictures is for a specific page the filename will start with the page name and contain no spaces.

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.

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 Next

Menu Paths

When describing a menu path, use the menu selection format.

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.

.. _bibles_sublevel:

Sublevel
========

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.

To convert a Bible using the command prompt in
Windows or a terminal in Linux or macOS you would type:

mod2osis biblename > biblename.osis

Codeing

When entering coding use the wrap the coding inside two ` characters.

``<div align="left">``

Toolbar Descriptions

When describing the items in a toolbar with one line descriptions, use the toolbar formatting.

|image| image description::
    some description about the image.

When the toolbar items need more detail, or you are documenting a feature, then use an inline Icon with Icon name

Selecting the |biblelock| Lock icon locks and unlocks the search results.  

This feature can be used to combine multiple search results into one ... 

End of File

Only leave upto one blank line at the end of the page.

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.