Changeset 371246c


Ignore:
Timestamp:
03/06/15 09:14:47 (3 months ago)
Author:
dlavigne <dru@…>
Branches:
master, enter/10, releng/10.1.2
Children:
55f5c8b
Parents:
1ab2d07
Message:

Cleanup final chapter.

Location:
docs
Files:
1 edited
6 moved

Legend:

Unmodified
Added
Removed
  • docs/support.rst

    reec7ac86 r371246c  
     1.. index:: advocacy 
     2.. _Supporting PC-BSD®: 
     3 
    14Supporting PC-BSD® 
    2 ****************** 
    3  
    4 PC-BSD® is a community project and relies on involvement from its users and supporters. 
    5 This section lists some ideas for becoming involved. 
    6  
    7  
    8  
    9  
    10  
    11  
    12  
    13  
    14  
    15  
    16  
    17  
    18  
     5******************* 
     6 
     7PC-BSD® is a community project and relies on involvement from its users and supporters. This section lists some ideas for becoming involved. 
     8 
     9* :ref:`Become a Beta Tester` 
     10 
     11* :ref:`Become a Translator` 
     12 
     13* :ref:`Become a Developer` 
     14 
     15* :ref:`Make Minor Modifications to a PBI Module` 
     16 
     17* :ref:`Purchase PC-BSD® Swag` 
     18 
     19* :ref:`Become an Advocate` 
     20 
     21.. index:: testing 
     22.. _Become a Beta Tester: 
    1923 
    2024Become a Beta Tester 
    2125==================== 
    2226 
    23 If you like playing around with operating systems and have a bit of spare time, one of the most effective ways you can assist the PC-BSD® community is by reporting problems you encounter while using PC-BSD®.  
    24  
    25 If you have a spare system or virtual machine, you can also download and try out the latest alpha, beta or release candidate snapshots. 
    26 These versions are still in testing and have not been officially released yet. 
    27 Having as many people as possible using PC-BSD® on many different hardware configurations assists the project in finding and fixing bugs. 
    28 This makes using PC-BSD® better for everyone. 
    29 Subscribing to the  is a good way to keep up-to-date on the availability of testing snapshots and any major bugs that are found within a snapshot. 
    30  
    31  
    32 If becoming a tester interests you, subscribe to the . As new testing versions become available they will be announced on this list. 
    33 You will also be able to see what problems other testers are finding and can check to see if the problem exists on your hardware as well. 
    34 You can also subscribe to  if you want a quick way to keep up with the subjects being discussed on the testing mailing list. 
    35  
    36  
    37 Anyone can become a beta tester. 
    38 Follow these tips so that you can accurately describe your findings so they can be fixed as soon as possible:  
    39  
    40 - before , search the testing mailing list to see if anyone else has reported a similar problem. 
     27If you like playing around with operating systems and have a bit of spare time, one of the most effective ways you can assist the PC-BSD® community is by 
     28reporting problems you encounter while using PC-BSD®.  
     29 
     30If you have a spare system or virtual machine, you can also download and try out the latest release candidate snapshots. These versions are still in testing 
     31and have not been officially released yet. Having as many people as possible using PC-BSD® on many different hardware configurations assists the project in 
     32finding and fixing bugs. This makes using PC-BSD® better for everyone. Subscribing to the `PC-BSD® blog <http://blog.pcbsd.org/>`_ is a good way to keep 
     33up-to-date on the availability of testing snapshots and any major bugs that are found within a snapshot. 
     34 
     35If becoming a tester interests you, subscribe to the `testing mailing list <http://lists.pcbsd.org/mailman/listinfo/testing>`_. As new testing versions become 
     36available they will be announced on this list. You will also be able to see what problems other testers are finding and can check to see if the problem exists 
     37on your hardware as well. You can also subscribe to `these RSS feeds <http://dir.gmane.org/gmane.os.pcbsd.testing>`_ if you want a quick way to keep up with 
     38the subjects being discussed on the testing mailing list. 
     39 
     40Anyone can become a beta tester. Follow these tips so that you can accurately describe your findings so they can be fixed as soon as possible:  
     41 
     42* Before you :ref:`Report a bug`, search the testing mailing list to see if anyone else has reported a similar problem. 
     43 
     44* When reporting a new issue, use a descriptive subject that includes the error and the version of PC-BSD®. Ideally, the subject is short (8 words or less) 
     45  and contains key words about the error. An example would be "Warden on 10-STABLE-p4 fails to export jail".  
     46 
     47* Ensure that the body of the bug report includes the PC-BSD® version. 
     48 
     49* Give a short (2-3 sentences) description of how to recreate the error (e.g. when I right click a jail in warden and select Export jail to a .wdn file, it 
     50  lets me select a file name, but then it freezes). If there is an error message, include its complete text. 
     51 
     52* Include any other info that may be useful (e.g. this used to work on 10.0). 
     53 
     54* If the problem appears to be hardware related, include a copy of :file:`/var/run/dmesg.boot` as this file shows the hardware that was probed the last time 
     55  the PC-BSD® system booted. 
    4156   
    42  
    43 - when reporting a new issue, use a descriptive subject that includes the error and the version of PC-BSD®. Ideally, the subject is short (8 words or less) and contains key words about the error. 
    44   An example would be “Warden on 10-STABLE-p4 fails to export jail”.  
    45  
    46 - ensure that the body of the bug report includes the PC-BSD® version. 
    47  
    48 - give a short (2-3 sentences) description of how to recreate the error (e.g. when I right click a jail in warden and select Export jail to a .wdn file, it lets me select a file name, but then it freezes). 
    49   If there is an error message, include its text. 
    50    
    51  
    52 - include any other info that may be useful (e.g. this used to work on 9.2). 
    53    
    54  
    55 - if the problem appears to be hardware related, include a copy of */var/run/dmesg.boot* as this file shows the hardware that was probed the last time the PC-BSD® system booted. 
    56    
    57  
     57.. index:: translations 
     58.. _Become a Translator: 
    5859 
    5960Become a Translator 
     
    6364 
    64651. Translate the graphical menus within the PC-BSD® operating system. 
    65     
    6666 
    67672. Translate the documentation that is published with PC-BSD®.  
    6868 
    69693. Translate the PC-BSD® website. 
    70     
    7170 
    7271This section describes each of these translation areas in more detail and how to get started as a translator. 
    7372 
    74  
    75  
    76 Join the Translations Mailing List 
    77 ---------------------------------- 
    78  
    79 Regardless of the type of translation you are interested in, you should first join the .When you join, send an email to introduce yourself and indicate which language(s) and which type(s) of translations you can assist with. 
    80 This will allow you to meet other volunteers as well as keep abreast of any notices or updates that may affect translators. 
    81  
    82  
     73Regardless of the type of translation you are interested in, you should first join the 
     74`translations mailing list <http://lists.pcbsd.org/mailman/listinfo/translations>`_. When you join, send an email to introduce yourself and indicate which 
     75language(s) and which type(s) of translations you can assist with. This will allow you to meet other volunteers as well as keep abreast of any notices or 
     76updates that may affect translators. 
     77 
     78.. index:: translations 
     79.. _Interface Translation: 
    8380 
    8481Interface Translation 
    8582--------------------- 
    8683 
    87 PC-BSD® uses for managing localization of the menu screens used by the installer and the PC-BSD® utilities. 
    88 Pootle makes it possible to find out if your native language has been fully localized for PC-BSD®. Pootle also makes it easy for users to check and submit translated text as it provides a web editor and commenting system. 
    89 This means that translators can spend their time making and reviewing translations rather than learning how to use a translation tool. 
    90  
    91  
    92 To see the status of a localization, open up the in a web browser, as seen in Figure 11.2a.  
     84PC-BSD® uses `Pootle <http://en.wikipedia.org/wiki/Pootle>`_ for managing localization of the menu screens used by the installer and the PC-BSD® utilities. 
     85Pootle makes it possible to find out if your native language has been fully localized for PC-BSD®. Pootle also makes it easy for users to check and submit 
     86translated text as it provides a web editor and commenting system. This means that translators can spend their time making and reviewing translations rather 
     87than learning how to use a translation tool. 
     88 
     89To see the status of a localization, open up the `translation website <http://translate.pcbsd.org/>`_ in a web browser, as seen in Figure 11.2a.  
    9390 
    9491**Figure 11.2a: The PC-BSD® Pootle Translation System**  
    9592 
    96 .. image:: images/picture_96.png 
    97  
    98 The localizations PC-BSD® users have requested are listed alphabetically on the left. 
    99 If your language is missing and you would like to help in its translation, send an email to the  so it can be added. 
    100  
    101  
    102 The green bar in the “Progress” column indicates the percentage of PC-BSD® menus that have been localized. 
    103 If a language is not at 100%, it means that the menus that currently are not translated will appear in English instead of in that language. 
    104  
    105  
    106 If you click on a language name then click on the “PC-BSD” hyperlink under the “Name” column, you will see each menu item that is available for translation. 
    107 The example shown in Figure 11.2b is for the Greek localization. 
    108 In this example, the menu for “ethernetconfig” is complete, but the one for “LifePreserver” is not. 
    109  
     93.. image:: images/translate1.png 
     94 
     95The localizations PC-BSD® users have requested are listed alphabetically on the left. If your language is missing and you would like to help in its 
     96translation, send an email to the `translations mailing list <http://lists.pcbsd.org/mailman/listinfo/translations>`_ so it can be added. 
     97 
     98The green bar in the "Progress" column indicates the percentage of PC-BSD® menus that have been localized. If a language is not at 100%, it means that the 
     99menus that currently are not translated will appear in English instead of in that language. 
     100 
     101If you click on a language name then click on the "PC-BSD" hyperlink under the "Name" column, you will see each menu item that is available for translation. 
     102The example shown in Figure 11.2b is for the Greek localization. In this example, the menu for "ethernetconfig" is complete, but the one for "LifePreserver" 
     103is not. 
    110104 
    111105**Figure 11.2b: Viewing a Language's Available Menus**  
    112106 
    113 .. image:: images/picture_87.png 
    114  
    115  
    116 Editing a Translation 
    117 ^^^^^^^^^^^^^^^^^^^^^ 
    118  
    119 In order to edit a translation, you need to first create a Pootle login account. 
    120 Once you are logged in to Pootle, navigate to the menu item that you wish to translate. 
    121 In Figure 11.2c, the translator has clicked on “LifePreserver.ts” then clicked the “Translate” tab. 
    122  
    123  
    124 **Figure 11.2****c****: Using the Pootle Interface to Edit a Translation String** 
    125  
    126 .. image:: images/picture_189.png 
    127  
    128 In this example, the first string, the phrase “Classic Home-Dir Backup” has not yet been translated. 
    129 To add the translation, type the translated text into the white text field and click the “Submit” button. 
    130 To translate another text field, click on the hyperlink associated with its name, or use the “Next” and “Previous” links to navigate between text fields. 
    131 Sometimes, a text field exists in another screen and already has a translation. 
    132 Figure 11.2d provides an example where the translator clicked the hyperlink for “Filename” which displays three previous translations. 
    133 The translator then clicked the first suggestion and it was automatically added to the white text field. 
    134  
    135 **Figure 11.2****d****: ****Selecting a Suggested Translation** 
    136  
    137 .. image:: images/picture_269.png 
    138  
    139 If you need help with a translation or using the Pootle system, you can ask for help on the translations mailing list or in the .  
    140  
     107.. image:: images/translate2.png 
     108 
     109In order to edit a translation, you need to first create a Pootle login account. Once you are logged in to Pootle, navigate to the menu item that you wish to 
     110translate. In Figure 11.2c, the translator has clicked on "LifePreserver.ts" then clicked the "Translate" tab. 
     111 
     112**Figure 11.2c: Using the Pootle Interface to Edit a Translation String** 
     113 
     114.. image:: images/translate3.png 
     115 
     116In this example, the first string, the phrase "Classic Home-Dir Backup" has not yet been translated. To add the translation, type the translated text into the 
     117white text field and click the "Submit" button. To translate another text field, click on the hyperlink associated with its name, or use the "Next" and 
     118"Previous" links to navigate between text fields. Sometimes, a text field exists in another screen and already has a translation. Figure 11.2d provides an 
     119example where the translator clicked the hyperlink for "Filename" which displays three previous translations. The translator then clicked the first suggestion 
     120and it was automatically added to the white text field. 
     121 
     122**Figure 11.2d: Selecting a Suggested Translation** 
     123 
     124.. image:: images/translate4.png 
     125 
     126If you need help with a translation or using the Pootle system, you can ask for help on the translations mailing list or in the 
     127`translations forum <http://forums.pcbsd.org/forumdisplay.php?f=19>`_.  
     128 
     129.. index:: translations 
     130.. _Documentation Translation: 
    141131 
    142132Documentation Translation 
    143133------------------------- 
    144134 
    145 The PC-BSD® Users Handbook is published with each version of PC-BSD®. The PC-BSD® wiki is used to create the next version of the Handbook. 
    146 As new features are added to the upcoming version of PC-BSD®, they are documented on the wiki. 
    147  
    148  
    149 The wiki has been configured with the . Wiki pages that are to appear in the published version of the Handbook has been marked with the translate tag so that they can be translated by translators. 
    150  
     135The PC-BSD® Users Handbook is published with each version of PC-BSD®. The PC-BSD® wiki is used to create the next version of the Handbook. As new features 
     136are added to the upcoming version of PC-BSD®, they are documented on the wiki. 
     137 
     138The wiki has been configured with the `MediaWiki translate extension <http://www.mediawiki.org/wiki/Help:Extension:Translate>`_. Wiki pages that are to appear 
     139in the published version of the Handbook has been marked with the translate tag so that they can be translated by translators. 
    151140 
    152141In order to translate a wiki page, you must first create a wiki account and log in. 
    153142 
    154  
    155 To translate a page, click the “Translate this page” link at the top of the page. 
    156 This will open the translation editor. 
    157 In the upper right corner, click the “Translate to English” drop-down menu to select the language you wish to translate into. 
    158 Once the language is selected, click the “Edit” link next to the string to be translated. 
    159 This will open an editor where you can type in the translation. 
    160 You can then either click the “Save translation” button to return to the previous page or click the “Skip to next” button to go to the next string to be translated. 
    161 In the example shown in Figure 11.2e, the user selected the Introduction page, clicked to translate to Russian, and has selected a paragraph to translate. 
    162  
    163  
    164 Figure 11.2e: Translating a Wiki Page 
    165  
    166 .. image:: images/picture_103.png 
    167  
    168 You can review the status of the translation by clicking the “Page” button at the bottom of the screen. 
    169 This will display the English and the translated versions side by side. 
    170  
    171  
    172 When translating, make sure to adhere to the following rules. 
    173 This is important as it ensures that the formatting of the published document is consistent across all translations. 
    174  
    175  
    176 - do not translate any text between formatting tags which are enclosed within < > brackets. 
    177    
    178  
    179 - do not translate the names of a command (such as **pc-updatemanager**) or application (such as AppCafe®). 
    180    
    181  
    182 - do not translate the output of a command unless it appears differently in a localized version of PC-BSD®.  
    183  
    184 - do not translate or remove any text contained between comment tags <!-- and -->.  
    185  
     143To translate a page, click the "Translate this page" link at the top of the page. This will open the translation editor. In the upper right corner, click the 
     144"Translate to English" drop-down menu to select the language you wish to translate into. Once the language is selected, click the "Edit" link next to the 
     145string to be translated. This will open an editor where you can type in the translation. You can then either click the "Save translation" button to return to 
     146the previous page or click the "Skip to next" button to go to the next string to be translated. In the example shown in Figure 11.2e, the user selected the 
     147Introduction page, clicked to translate to Russian, and has selected a paragraph to translate. 
     148 
     149**Figure 11.2e: Translating a Wiki Page** 
     150 
     151.. image:: images/translate5.png 
     152 
     153You can review the status of the translation by clicking the "Page" button at the bottom of the screen. This will display the English and the translated 
     154versions side by side. 
     155 
     156When translating, make sure to adhere to the following rules. This is important as it ensures that the formatting of the published document is consistent 
     157across all translations. 
     158 
     159* Do not translate any text between formatting tags which are enclosed within "< >" brackets. 
     160 
     161* Do not translate the names of a command (such as :command:`pc-updatemanager`) or application (such as "AppCafe®"). 
     162 
     163* Do not translate the output of a command unless it appears differently in a localized version of PC-BSD®.  
     164 
     165* Do not translate or remove any text contained between comment tags "<!-- and -->".  
     166 
     167.. index:: translations 
     168.. _Website Translation: 
    186169 
    187170Website Translation 
    188171------------------- 
    189172 
    190 If you are interested in translating the PC-BSD® website, send an email to the . Someone will introduce you to the webmaster who will get you started on website translation. 
    191  
     173If you are interested in translating the PC-BSD® website, send an email to the 
     174`translations mailing list <http://lists.pcbsd.org/mailman/listinfo/translations>`_. Someone will introduce you to the webmaster who will get you started on 
     175website translation. 
    192176 
    193177Currently, the following translated websites are available:  
    194178 
     179* `French <http://www.pcbsd.org/fr/>`_ 
     180 
     181* `Spanish <http://www.pcbsd.org/es/>`_ 
     182 
     183.. index:: development 
     184.. _Become a Developer: 
    195185 
    196186Become a Developer 
    197187================== 
    198188 
    199 If you like programming, and especially coding on FreeBSD, we would love to see you join the as a PC-BSD® committer. 
    200 Developers who want to help improve the PC-BSD® codebase are always welcome! If you would like to participate in core development, subscribe to the . Once you have signed up, feel free to browse the active tickets in the PC-BSD® . If you see something that you want to work on, or have a proposal for a project you wish to add to PC-BSD®, please let us know via the developers list and we will be happy to help get you started. 
    201  
    202  
    203 Most of the PC-BSD® specific GUI tools are developed in C++ using the Qt Libraries, and other non-GUI development is done using standard Bourne shell scripts. 
    204 There may be cases where other languages or libraries are needed, but those will be evaluated on a case-by-case basis, so feel free to let us know your proposals on the developers mailing list. 
    205  
    206  
    207  
    208 Getting the Source Code and Development Tools  
    209 ---------------------------------------------- 
    210  
    211 The PC-BSD® source code is available from github and **git** needs to be installed in order to download the source code. 
    212 When using PC-BSD®, **git** is included in the base install. 
    213  
    214  
    215 To download the source code, **cd** to the directory to store the source and type:  
    216  
    217 **git clone git://github.com/pcbsd/pcbsd.git**  
    218  
    219 This will create a directory named *pcbsd/* which contains the local copy of the repository. 
    220 To keep the local copy in sync with the official repository, run **git pull** within the *pcbsd* directory. 
    221  
    222  
    223 PC-BSD® graphical applications use Qt version 5 and their source is located in *pcbsd/src-qt**5**/*. 
    224 In order to compile the applications in this directory, install the “PC-BSD Build ToolChain” PBI using . To instead install this PBI from the command line, type **pbi add ****devel/****pcbsd-toolchain**. 
    225  
     189If you like programming, and especially coding on FreeBSD, we would love to see you join the as a PC-BSD® committer. Developers who want to help improve the 
     190PC-BSD® codebase are always welcome! If you would like to participate in core development, subscribe to the 
     191`developers mailing list <http://lists.pcbsd.org/mailman/listinfo/dev>`_. Once you have signed up, feel free to browse the active tickets in the PC-BSD® 
     192`bug tracker <https://bugs.pcbsd.org/projects/pcbsd/>`_. If you see something that you want to work on, or have a proposal for a project you wish to add to 
     193PC-BSD®, please let us know via the developers list and we will be happy to help get you started. 
     194 
     195Most of the PC-BSD® specific GUI tools are developed in C++ using the Qt Libraries, and other non-GUI development is done using standard Bourne shell 
     196scripts. There may be cases where other languages or libraries are needed, but those will be evaluated on a case-by-case basis, so feel free to let us know 
     197your proposals on the developers mailing list. 
     198 
     199.. index:: development 
     200.. _Getting the Source Code: 
     201 
     202Getting the Source Code 
     203----------------------- 
     204 
     205The PC-BSD® source code is available from github and :command:`git` needs to be installed in order to download the source code. When using PC-BSD®, 
     206:command:`git` is included in the base install. 
     207 
     208To download the source code, :command:`cd` to the directory to store the source and type:: 
     209 
     210 git clone git://github.com/pcbsd/pcbsd.git 
     211 
     212This will create a directory named :file:`pcbsd/` which contains the local copy of the repository. To keep the local copy in sync with the official 
     213repository, run :command:`git pull` within the :file:`pcbsd` directory. 
     214 
     215PC-BSD® graphical applications use Qt version 5 and their source is located in :file:`pcbsd/src-qt5/`. In order to compile the applications in this 
     216directory, install the "PC-BSD Build ToolChain" PBI using :ref:`AppCafe®`. To instead install this PBI from the command line, type 
     217:command:`pbi add devel/pcbsd-toolchain`. 
    226218 
    227219Most of the PC-BSD® source code is divided into two sub-categories:  
    228220 
    229 - *src-sh/* contains shell and C programs which do not include GUIs. 
    230   These are the command line utilities used in TrueOS® and PC-BSD® and which are installed by the FreeBSD sysutils/pcbsd-utils port. 
    231    
    232  
    233 - *src-qt**5**/* contains the Qt5-based GUIs seen in PC-BSD® and which are installed by the FreeBSD sysutils/pcbsd-utils-qt5 port  
    234  
    235 To compile the command line utilities:  
    236  
    237 **cd src-sh**  
    238  
    239 **make**  
    240  
    241 To compile the graphical utilities:  
    242  
    243 **cd src-qt4**  
    244  
    245 **/usr/local/lib/qt5/bin/qmake**  
    246  
    247 **make**  
    248  
    249 Several Qt IDEs are available in AppCafe®. The  PBI is a full featured IDE designed to help new Qt users get up and running faster while boosting the productivity of experienced Qt developers. 
    250 is lighter weight as it is only a *.ui* file editor and does not provide any other IDE functionality. 
    251 It can be installed as the “qt5-designer” raw package using AppCafe® or **pkg install**. 
    252  
    253  
    254 If you plan to submit changes so that they can be included in PC-BSD®, fork the repository using the instructions at . Make your changes to the fork, then submit them by issuing a . Once your changes have been reviewed, they will be committed or sent back with suggestions. 
    255  
    256  
    257  
    258 Basic Guidelines for Writing a PC-BSD® Utility  
    259 ----------------------------------------------- 
    260  
    261 PC-BSD® is a community driven project that relies on the support of developers in the community to help in the design and implementation of new utilities and tools for PC-BSD®. Going forward, we aim to present a unified design so that programs feel familiar to users. 
    262 As an example, while programs could have “File”, “Main”, or “System” as their first entry on the “File menu”, we want to present one option, “File”, as it is the accepted norm for the first category on the menu bar. 
    263  
    264  
    265 This section describes a small list of guidelines to menu and program design in PC-BSD®. Since most programs designed for the last couple of decades have followed this structure, it makes sense for us to follow the same standard. 
    266  
    267  
    268  
    269 File Menus  
    270 ^^^^^^^^^^^ 
    271  
    272 Any graphical program that is a full-featured utility, such as Warden® or AppCafe®, should have a file menu. 
    273 However, file menus are not necessary for small widget programs or dialogue boxes. 
    274 When making a file menu, a good rule of thumb is keep it simple. 
    275 Most PC-BSD® utilities do not need more than two or three items on the file menu. 
    276 An example of a well laid out “File” menu is AppCafe®, shown in Figure 11.3a.  
    277  
    278 Figure 11.3a: AppCafe® File Menu 
    279  
    280 .. image:: images/picture_217.png 
    281  
    282 â€œConfigure” is our adopted standard for the category that contains “Settings” or other configuration related settings. 
    283 If additional categories are needed, check to see what other PC-BSD® utilities are using. 
    284  
    285  
    286  
    287 File Menu Icons  
    288 ^^^^^^^^^^^^^^^^ 
    289  
    290 File menu icons are taken from the KDE Oxygen theme located in */usr/local/share/icons/oxygen*. 
    291 Use these file menu icons so we do not have a bunch of different icons used for the same function. 
    292 Table 11.3a lists the commonly used icons and their default file names. 
     221* :file:`src-sh/` contains shell and C programs which do not include GUIs. These are the command line utilities used in TrueOS® and PC-BSD® and which are 
     222  installed by the FreeBSD sysutils/pcbsd-utils port. 
     223 
     224* :file:`src-qt5/` contains the Qt5-based GUIs seen in PC-BSD® and which are installed by the FreeBSD sysutils/pcbsd-utils-qt5 port  
     225 
     226To compile the command line utilities:: 
     227 
     228 cd src-sh 
     229 
     230 make 
     231 
     232To compile the graphical utilities:: 
     233 
     234 cd src-qt4 
     235 
     236 /usr/local/lib/qt5/bin/qmake 
     237 
     238 make 
     239 
     240Several Qt IDEs are available in :ref:`AppCafe®`. The `QtCreator <http://qt-project.org/wiki/Category:Tools::QtCreator>`_ PBI is a full featured IDE designed 
     241to help new Qt users get up and running faster while boosting the productivity of experienced Qt developers. 
     242`Qt Designer <http://qt-project.org/doc/qt-4.8/designer-manual.html>`_ is lighter weight as it is only a :file:`.ui` file editor and does not provide any 
     243other IDE functionality. It can be installed as the "qt5-designer" raw package using AppCafe® or :command:`pkg install`. 
     244 
     245If you plan to submit changes so that they can be included in PC-BSD®, fork the repository using the instructions at 
     246`fork a repo <https://help.github.com/articles/fork-a-repo>`_. Make your changes to the fork, then submit them by issuing a 
     247`git pull request <https://help.github.com/articles/using-pull-requests>`_. Once your changes have been reviewed, they will be committed or sent back with 
     248suggestions. 
     249 
     250.. index:: development 
     251.. _Design Guidelines: 
     252 
     253Design Guidelines 
     254----------------- 
     255 
     256PC-BSD® is a community driven project that relies on the support of developers in the community to help in the design and implementation of new utilities and 
     257tools for PC-BSD®. Going forward, we aim to present a unified design so that programs feel familiar to users. As an example, while programs could have 
     258"File", "Main", or "System" as their first entry on the "File" menu, "File" is used as the accepted norm for the first category on the menu bar. 
     259 
     260This section describes a small list of guidelines to menu and program design in PC-BSD®. Since most programs designed for the last couple of decades have 
     261followed this structure, it makes sense for us to follow the same standard. 
     262 
     263Any graphical program that is a full-featured utility, such as :ref:`Warden®` or :ref:`AppCafe®`, should have a "File" menu. However, file menus are not 
     264necessary for small widget programs or dialogue boxes. When making a file menu, a good rule of thumb is keep it simple. Most PC-BSD® utilities do not need 
     265more than two or three items on the file menu. An example of a well laid out "File" menu is :ref:`AppCafe®`, shown in Figure 11.3a.  
     266 
     267**Figure 11.3a: AppCafe® File Menu** 
     268 
     269.. image:: images/dev1.png 
     270 
     271"Configure" is our adopted standard for the category that contains settings or configuration-related settings. If additional categories are needed, check to 
     272see what other PC-BSD® utilities are using. 
     273 
     274File menu icons are taken from the KDE Oxygen theme located in :file:`/usr/local/share/icons/oxygen`. Use these file menu icons so we do not have a bunch of 
     275different icons used for the same function. Table 11.3a lists the commonly used icons and their default file names. 
    293276 
    294277 
     
    297280+-----------+-----------------+--------------------+ 
    298281| Function  | File Menu Icon  | File Name          | 
    299 +-----------+-----------------+--------------------+ 
    300 | Quit      | row 1, cell 2   | window\-close.png  | 
     282+===========+=================+====================+ 
     283| Quit      | row 1, cell 2   | window-close.png   | 
    301284+-----------+-----------------+--------------------+ 
    302285| Settings  | row 2, cell 2   | configure.png      | 
     
    304287 
    305288 
    306 Buttons  
    307 ^^^^^^^^ 
    308  
    309289PC-BSD® utilities use these buttons as follows:  
    310290 
    311 - **Apply:** applies settings and leaves the window open. 
    312    
    313  
    314 - **Close:** closes program without applying settings. 
    315    
    316  
    317 - **OK:** closes dialogue window and saves settings. 
    318    
    319  
    320 - **Cancel:** closes dialogue window without applying settings. 
    321    
    322  
    323 - **Save:** saves settings and closes window. 
    324    
    325  
    326 Fully functional programs like  and  do not use close buttons on the front of the application. 
    327 Basically, whenever there is a “File” menu, that and an x in the top right corner of the application are used instead. 
    328 Dialogues and widget programs are exceptions to this rule. 
    329 A good example of a widget program would be .  
    330  
    331  
    332 Keyboard Shortcuts  
    333 ^^^^^^^^^^^^^^^^^^^ 
    334  
    335 Many users benefit from keyboard shortcuts and we aim to make them available in every PC-BSD® utility. 
    336 Qt makes it easy to assign keyboard shortcuts. 
    337 For instance, to configure keyboard shortcuts that browse the “File” menu, put *&File* in the text slot for the menu entry when making the application. 
    338 Whichever letter has the & symbol in front of it will become the hot key. 
    339 You can also make a shortcut key by clicking the menu or submenu entry and assigning a shortcut key. 
    340 Be careful not to duplicate hot keys or shortcut keys. 
    341 Every key in a menu and submenu should have a key assigned for ease of use and accessibility. 
    342 Tables 11.3b and 11.3c summarize the commonly used shortcut and hot keys. 
    343  
     291* **Apply:** applies settings and leaves the window open. 
     292 
     293* **Close:** closes program without applying settings. 
     294 
     295* **OK:** closes dialogue window and saves settings. 
     296 
     297* **Cancel:** closes dialogue window without applying settings. 
     298 
     299* **Save:** saves settings and closes window. 
     300 
     301Fully functional programs like :ref:`AppCafe®` and :ref:`Warden®` do not use close buttons on the front of the application. Basically, whenever there is a 
     302"File" menu, that and an "x" in the top right corner of the application are used instead. Dialogues and widget programs are exceptions to this rule. A good 
     303example of a widget program would be :ref:`Update Manager`.  
     304 
     305Many users benefit from keyboard shortcuts and we aim to make them available in every PC-BSD® utility. Qt makes it easy to assign keyboard shortcuts. For 
     306instance, to configure keyboard shortcuts that browse the "File" menu, put *&File* in the text slot for the menu entry when making the application. 
     307Whichever letter has the *&* symbol in front of it will become the hot key. You can also make a shortcut key by clicking the menu or submenu entry and 
     308assigning a shortcut key. Be careful not to duplicate hot keys or shortcut keys. Every key in a menu and submenu should have a key assigned for ease of use 
     309and accessibility. Tables 11.3b and 11.3c summarize the commonly used shortcut and hot keys. 
    344310 
    345311**Table 11.3b: Shortcut Keys**  
     
    347313+---------------+---------+ 
    348314| Shortcut Key  | Action  | 
    349 +---------------+---------+ 
    350 | CTRL \+ Q     | Quit    | 
     315+===============+=========+ 
     316| CTRL + Q      | Quit    | 
    351317+---------------+---------+ 
    352318| F1            | Help    | 
     
    357323+-----------+-----------------+ 
    358324| Hot Key   | Action          | 
    359 +-----------+-----------------+ 
    360 | Alt \+ Q  | Quit            | 
    361 +-----------+-----------------+ 
    362 | Alt \+ S  | Settings        | 
    363 +-----------+-----------------+ 
    364 | Alt \+ I  | Import          | 
    365 +-----------+-----------------+ 
    366 | Alt \+ E  | Export          | 
    367 +-----------+-----------------+ 
    368 | ALT \+ F  | File Menu       | 
    369 +-----------+-----------------+ 
    370 | ALT \+ C  | Configure Menu  | 
    371 +-----------+-----------------+ 
    372 | ALT \+ H  | Help Menu       | 
    373 +-----------+-----------------+ 
    374  
    375  
    376 Saving Settings in a Qt Application  
    377 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
    378  
    379 When saving an application's settings, the QSettings class should be used if possible. 
    380 There are two different “organizations”, depending on whether the application is running with root permissions or user permissions. 
    381 Use “PCBSD” for the organization for applications that run with user permissions and “PCBSD-root” for applications that are started with root permissions via **sudo**. 
    382 Proper use prevents the directory where settings files are saved from being locked down by root applications, allowing user applications to save and load their settings. 
    383 Examples 11.3a and 11.3b demonstrate how to use the QSettings class for each type of permission. 
    384  
     325+===========+=================+ 
     326| Alt + Q   | Quit            | 
     327+-----------+-----------------+ 
     328| Alt + S   | Settings        | 
     329+-----------+-----------------+ 
     330| Alt + I   | Import          | 
     331+-----------+-----------------+ 
     332| Alt + E   | Export          | 
     333+-----------+-----------------+ 
     334| ALT + F   | File Menu       | 
     335+-----------+-----------------+ 
     336| ALT + C   | Configure Menu  | 
     337+-----------+-----------------+ 
     338| ALT + H   | Help Menu       | 
     339+-----------+-----------------+ 
     340 
     341When saving an application's settings, the QSettings class should be used if possible. There are two different "organizations", depending on whether the 
     342application is running with *root* permissions or user permissions. Use "PCBSD" for the organization for applications that run with user permissions and 
     343"PCBSD-root" for applications that are started with root permissions via :command:`sudo`. Proper use prevents the directory where settings files are saved 
     344from being locked down by *root* applications, allowing user applications to save and load their settings. Examples 11.3a and 11.3b demonstrate how to use the 
     345QSettings class for each type of permission. 
    385346 
    386347**Example 11.3a: User Permission Settings**  
    387  
    388 (user application - C++ code):  
    389  
    390 QSettings settings("PCBSD", "myapplication"); 
     348:: 
     349 (user application - C++ code):  
     350 QSettings settings("PCBSD", "myapplication"); 
    391351 
    392352**Example 11.3b: Root Permission Settings**  
    393  
    394 (root application - C++ code): 
    395  
    396 QSettings settings("PCBSD-root", "myapplication"); 
    397  
    398  
    399 Resources  
    400 ---------- 
     353:: 
     354 (root application - C++ code): 
     355 QSettings settings("PCBSD-root", "myapplication"); 
     356 
    401357 
    402358Developers will also find the following resources helpful:  
    403359 
    404  
    405 Make Minor Modifications to a PBI Module  
    406 ========================================= 
    407  
    408 If you have a GitHub account and are logged in, you can contribute minor PBI changes to the  using a web browser. 
    409 If you do not have a GitHub account, create one  and use a valid email address as you will need to confirm your email address. 
    410  
    411  
    412 For example, to add a screenshot for an application, upload the screenshot file to a publicly accessible site, then add the URL to the screenshot in between the quotes of the *PBI_SCREENSHOTS=""* line in the *pbi.conf* file for that module. 
    413 Or, to add a similar application, put the package category and package name in between the *PBI_PLUGINS=""* line in the *pbi.conf* file for that module. 
    414 As an example, refer to the . More information about the the available *pbi.conf* variables can be found in Table 8.1a.  
    415  
    416 To make the edit, click on the *pbi.conf* file for the module, click the “Edit” button, make the change, then click the “Commit changes” button. 
    417 This will issue a “git pull” request which will be reviewed by a developer who will either approve it or contact you if more information about the edit is needed. 
    418 Once the request is approved, you will receive an email about the approval and the change will appear in  when the next package set becomes available. 
    419 How long that takes depends upon whether the system is set to use the PRODUCTION or EDGE package set. 
    420  
    421  
     360* `Commits Mailing List <http://lists.pcbsd.org/mailman/listinfo/commits>`_ 
     361 
     362* `Qt 5.4 Documenation <http://doc.qt.io/qt-5/index.html>`_ 
     363 
     364* `C++ Tutorials <http://www.cplusplus.com/doc/tutorial/>`_ 
     365 
     366.. index:: development 
     367.. _Make Minor Modifications to a PBI Module: 
     368 
     369Make Minor Modifications to a PBI Module 
     370======================================== 
     371 
     372If you have a GitHub account and are logged in, you can contribute minor PBI changes to the 
     373`pbi-modules repository <https://github.com/pcbsd/pcbsd/tree/master/pbi-modules>`_ using a web browser. If you do not have a GitHub account, 
     374`create one <https://github.com/>`_ and use a valid email address as you will need to confirm your email address. 
     375 
     376For example, to add a screenshot for an application, upload the screenshot file to a publicly accessible site, then add the URL to the screenshot in between 
     377the quotes of the *PBI_SCREENSHOTS=""* line in the :file:`pbi.conf` file for that module. Or, to add a similar application, put the package category and 
     378package name in between the *PBI_PLUGINS=""* line in the :file:`pbi.conf` file for that module. As an example, refer to the 
     379`pbi.conf for the www/firefox PBI module <https://github.com/pcbsd/pcbsd/blob/master/pbi-modules/www/firefox/pbi.conf>`_. More information about the the 
     380available :file:`pbi.conf` variables can be found in Table 8.1a.  
     381 
     382To make the edit, click on the :file:`pbi.conf` file for the module, click the "Edit" button, make the change, then click the "Commit changes" button. This 
     383will issue a "git pull" request which will be reviewed by a developer who will either approve it or contact you if more information about the edit is needed. 
     384Once the request is approved, you will receive an email about the approval and the change will appear in :ref:`AppCafe®` when the next package set becomes 
     385available. How long that takes depends upon whether the system is set to use the PRODUCTION or EDGE package set. 
     386 
     387.. index:: advocacy 
     388.. _Purchase PC-BSD® Swag: 
    422389 
    423390Purchase PC-BSD® Swag 
    424 ===================== 
    425  
    426 While PC-BSD® is free, some users may wish to purchase media or other items to show their support for the PC-BSD® Project. 
    427 PC-BSD® items are available from the following websites:  
    428  
    429 -  sells PC-BSD® DVDs and subscriptions, stickers, The Definitive Guide to PC-BSD®, and apparel. 
    430    
    431  
    432 - **Amazon:** sells The Definitive Guide to PC-BSD® (hard copy and Kindle formats) as well as the Kindle versions of the PC-BSD® Handbook. 
    433   Items are available for purchase in your country may vary. 
    434    
    435  
    436 -  sells high-quality apparel and accessories. 
    437    
    438  
     391====================== 
     392 
     393While PC-BSD® is free, some users may wish to purchase media or other items to show their support for the PC-BSD® Project. PC-BSD® items are available from 
     394the following websites:  
     395 
     396* `FreeBSD Mall <http://www.freebsdmall.com/cgi-bin/fm/scan/fi=prod_bsd/tf=list_order/sf=sku/sf=title/sf=category/se=pc-bsd?id=B3TkJm7G&mv_pc=5>`_: sells 
     397  PC-BSD® DVDs and subscriptions, stickers, The Definitive Guide to PC-BSD®, and apparel.  
     398 
     399* Amazon: sells The Definitive Guide to PC-BSD® (hard copy and Kindle formats) as well as the Kindle versions of the PC-BSD® Handbook. Items available for 
     400  purchase in your country may vary.  
     401 
     402* `The PC-BSD® Corporate Storefront <http://pcbsd.qbstores.com/>`_: sells high-quality apparel and accessories.  
     403 
     404.. index:: advocacy 
     405.. _Become an Advocate: 
    439406 
    440407Become an Advocate 
    441408================== 
    442409 
    443 So you love PC-BSD®? Why not tell your family, friends, fellow students and colleagues about it? You will not be the only one that likes a virus-free, feature-rich, no-cost operating system. 
    444 Here are some suggestions to get you started:  
    445  
    446 - Burn a couple of DVDs and pass them out. 
    447   If your school or user group has an upcoming event where you can promote PC-BSD®, you can request additional DVDs from sales@pcbsd.com. 
    448    
    449  
    450 - Consider giving a presentation about PC-BSD® at a local community event or conference. 
    451   Let us know about it and we will help you spread the word. 
    452    
    453  
    454 - Write a personal blog detailing your journey from your first PC-BSD® install experience to your most recent accomplishment. 
    455   The blog could also be used to teach or explain how to perform tasks on PC-BSD®. A regional language blog may help build the community in your area and to find others with similar interests. 
    456    
    457  
    458 .. |picture_177| image:: images/picture_177.png 
    459  
    460 .. |picture_92| image:: images/picture_92.png 
    461  
    462 .. |picture_98| image:: images/picture_98.png 
    463  
    464 .. |picture_147| image:: images/picture_147.png 
    465  
    466 .. |picture_195| image:: images/picture_195.png 
    467  
    468 .. |picture_137| image:: images/picture_137.png 
     410So you love PC-BSD®? Why not tell your family, friends, fellow students and colleagues about it? You will not be the only one that likes a virus-free, 
     411feature-rich, no-cost operating system. Here are some suggestions to get you started:  
     412 
     413* Burn a couple of DVDs and pass them out. If your school or user group has an upcoming event where you can promote PC-BSD®, you can request additional DVDs 
     414  from sales@pcbsd.com. 
     415 
     416* Consider giving a presentation about PC-BSD® at a local community event or conference. Let us know about it and we will help you spread the word. 
     417 
     418* Write a personal blog detailing your journey from your first PC-BSD® install experience to your most recent accomplishment. The blog could also be used to 
     419  teach or explain how to perform tasks on PC-BSD®. A regional language blog may help build the community in your area and to find others with similar 
     420  interests. 
Note: See TracChangeset for help on using the changeset viewer.