SystemDocumentation

The backed up content of this page is deprecated and will rank lower in search results!

Clear message

How to edit the Kubuntu system documentation

This page provides instructions and resources for contributing to the Kubuntu system documentation. Be aware that most of this information is somewhat outdated, as we now develop our documentation on the KDE Userbase wiki at Kubuntu Documentation Userbase. All you need is an Identity account to get started. When finished, our docs are translated, then put on the ISO and on the website. So take the below with a grain of salt!

Getting started

These four things are required:

  1. An account with Launchpad.

  2. Bazaar version control software.

  3. KGpg encryption software.

  4. OpenSSH encrypted connectivity software.

See step by step instructions for each of them below.

Create a Launchpad account

Visit the Launchpad web site at https://launchpad.net/ and click the Log in / Register link in the upper right corner of the page to create an account.

Install and configure Bazaar

Bazaar is version control software for tracking the history of a project, and is available as a Kubuntu package.

  1. Install Bazaar:

    1. Open the K menu in your panel.

    2. Left-click System.

    3. Left-click Konsole.

    4. Type this command at the prompt:

      sudo apt-get install bzr
    5. Press the Enter key.

    6. Type your Kubuntu password at the prompt.

    7. Close the Konsole window.

  2. Configure Bazaar:

    1. Open the K menu in your panel.

    2. Left-click System.

    3. Left-click Konsole.

    4. Tell Bazaar who you are by typing this command at the prompt, replacing USERNAME with your Launchpad username and USERNAME@ADDRESS.COM with the email address you use for Launchpad:

      bzr whoami USERNAME <USERNAME@ADDRESS.COM>
    5. Press the Enter key.

    6. Close the Konsole window.

Install and configure KGpg

KGpg is encryption software, and is available as a Kubuntu package.

  1. Install KGpg:

    1. Open the K menu in your panel.

    2. Left-click System.

    3. Left-click Konsole.

    4. Type this command at the prompt:

      sudo apt-get install kgpg
    5. Press the Enter key.

    6. Type your Kubuntu password at the prompt.

    7. Close the Konsole window.

  2. Configure KGpg:

    1. Open the K menu in your panel.

    2. Left-click Utilities.

    3. Left-click KGpg. The assistant will open.

    4. Left-click the Next button. It will display the path to its binary.

    5. Left-click the Next button. It will display the path to its configuration file.

    6. Left-click the Next button. It will offer to create a new key and start KGpg automatically on KDE start-up.

    7. Uncheck the box next to Start KGpg automatically at KDE startup.

    8. Left-click the Finish button. The key generation interface will open.

    9. Type the user name you would like to use for KGpg into the Name box.

    10. Type your email address into the Email box.

    11. Left-click the OK button.

    12. Type the password you would like to use into the Password box.

    13. Type the same password into the Verify box.

    14. Left-click the OK button to generate your key pair. When it's finished, it will display a notification window displaying your fingerprint and offering to print a revocation certificate.

      • If you get a message saying that the gpg process did not finish and that a new key pair could not be generated, this is a known KDE bug that can be overcome by following these steps:

        1. Left-click the Settings menu.

        2. Left-click Configure KGpg...

        3. Left-click Gnu PG Settings in the left panel.

        4. Change gpg to gpg2 in the Program path box.

        5. Left-click the Apply button.

        6. Left-click the OK button.

        7. Left-click the Keys menu.

        8. Left-click Generate Key Pair... The key generation interface will open.

        9. Type the user name you would like to use for KGpg into the Name box.

        10. Type your email address into the Email box.

        11. Left-click the OK button.

        12. Type the password you would like to use into the Password box.

        13. Type the same password into the Verify box.

        14. Left-click the OK button to generate your key pair.

    15. Check the box next to Save as:.

    16. Left-click the OK button.

    17. Left-click your key in the main pane by left-clicking it.

    18. Left-click the Export Public Key button above it. An interface will open.

    19. Make sure the radio button next to File is selected (it should be by default).

    20. Make sure the radio button next to Export everything is selected (it should be by default).

    21. Left-click the OK button. A notification will display letting you know that the public key was successfully exported and displaying the path to the file.

Install and configure OpenSSH

OpenSSH is encrypted connectivity client software, and is available as a Kubuntu package.

  1. Install OpenSSH:

    1. Open the K menu in your panel.

    2. Left-click System.

    3. Left-click Konsole.

    4. Type this command at the prompt:

      sudo apt-get install openssh-client
    5. Press the Enter key.

    6. Type your Kubuntu password at the prompt.

    7. Close the Konsole window.

  2. Configure OpenSSH:

    1. Left-click the K menu in your panel.

    2. Left-click System.

    3. Left-click Konsole.

    4. Type this command at the prompt to create the hidden ssh directory in your home directory:

      mkdir ~/.ssh
    5. Press the Enter key.

    6. Type this command at the prompt so that only you have permission to read, write, or execute in the hidden ssh directory you created:

      chmod 700 ~/.ssh
    7. Press the Enter key.

    8. Type this command at the prompt to generate a key pair:

      ssh-keygen -t rsa
    9. Press the Enter key. It will generate the public/private key pair and ask for a path to a file in which to save the key. It will recommend a path.

    10. Type the path it recommended at the prompt, copying it exactly, because if you ever need outside help with your set-up, most help pages reference the default path.

    11. Press the Enter key. It will ask you for a passphrase.

    12. Type a password or passphrase at the prompt.

    13. Press the Enter key. It will notify you that your identification and public key have been saved, and it will display the path to both. Your key fingerprint and random art image will also be displayed.

    14. Close the Konsole window.

Configure your Launchpad account

  1. Visit the Launchpad web site at https://launchpad.net/ with your browser.

  2. Left-click the Log in / Register link in the upper right corner of the page to log in, providing your username and password when asked.

  3. Left-click your user name in the upper right corner of the page to go to your account overview.

  4. Configure your OpenPGP keys:

    1. Left-click the pencil icon next to OpenPGP keys.

    2. Open the K menu in your panel.

    3. Left-click Utilities.

    4. Left-click KGpg.

    5. Left-click the Key Properties button in the toolbar.

    6. Right-click the content in the Fingerprint box in the bottom pane of the window.

    7. Left-click Select All.

    8. Right-click the content in the Fingerprint box in the bottom pane of the window.

    9. Left-click Copy.

    10. Right-click inside the Fingerprint box on the Launchpad page.

    11. Left-click Paste.

    12. Left-click the Import Key button at the bottom of the page.

    13. Left-click the Overview link at the top of the page.

    14. Close the KGpg windows.

    15. Check the email account you gave to Launchpad for a confirmation message.

    16. Click the link in the confirmation message to add the key to your Launchpad account.

  5. Configure your SSH keys:

    1. Left-click the pencil icon next to SSH keys.

    2. Open the K menu in your panel.

    3. Left-click System.

    4. Left-click Konsole.

    5. Type this command at the prompt:

      cat ~/.ssh/id_rsa.pub
    6. Hold down the left mouse button and drag the mouse across the output of that command to select it.

    7. Left-click the Edit button in the menu.

    8. Left-click Copy.

    9. Right-click inside the large box in the Launchpad SSH keys page.

    10. Left-click Paste.

    11. Left-click the Import Public Key button at the bottom of the page.

    12. Left-click the Overview link at the top of the page.

  6. Sign the Ubuntu Code of Conduct:

    1. Left-click the pencil icon next to No under Signed Ubuntu Code of Conduct.

    2. Left-click the Download link in step 2 on the Launchpad page.

    3. Open the file in a text editor and read it to be certain that you agree with it.

    4. Close the text editor.

    5. Open a Konsole terminal window in the directory the Ubuntu Code of Conduct was saved into.

    6. Type this command at the prompt:

      gpg --clearsign UbuntuCodeofConduct-1.1.txt
    7. Type in your KGpg password. A signed copy of the file will be created as UbuntuCodeofConduct-1.1.txt.asc.

    8. Type this command at the prompt to display the contents of the signed file:

      cat UbuntuCodeofConduct-1.1.txt.asc
    9. Hold down the left mouse button and drag the mouse across the output of that command to select it.

    10. Left-click the Edit button in the menu.

    11. Left-click Copy.

    12. Left-click the Sign it! link in step 3 on the Launchpad page.

    13. Right-click inside the Signed code box on the Launchpad page.

    14. Left-click Paste.

    15. Left-click the Continue button at the bottom of the page.

    16. Left-click the Overview link at the top of the page.

    17. Left-click the Log Out button in the upper right corner of the page.

Get the Kubuntu documentation

  1. Left-click the K menu.

  2. Left-click System.

  3. Left-click Konsole.

  4. Type this commmand at the prompt, replacing PATH with the complete path to the directory you would like to put the Kubuntu documentation directory into, to enter that directory:

    cd /PATH
  5. Type this command at the prompt to log in to Launchpad, replacing USERNAME with your Launchpad user name:

    bzr launchpad-login USERNAME
  6. Type this command at the prompt to create the kubuntu-docs working copy directory inside the current directory from the Launchpad files:

    bzr branch lp:kubuntu-docs
  7. Type your OpenSSH password when asked for it. A message will be displayed letting you know how many revisions have been branched.

Work on the Kubuntu documentation

  1. Get the latest copy of the files (this only works if your working copy has no new unpushed commits) by opening a terminal window in the working copy directory and typing this command at the prompt:

    bzr pull
  2. Choose a document in the docs subdirectory to work on.

  3. Log in to Launchpad by opening the https://code.launchpad.net/~ page in your browser.

  4. Open the https://blueprints.launchpad.net/ubuntu/+spec/kubuntu-q-docs page in your browser to access the Launchpad blueprints.

  5. Update the work item by changing its state from TODO to IN PROGRESS.

  6. Make changes to the files normally using the program or programs you prefer for working with text, using the DocBook elements and DocBook entities resource sections below as a guide.

  7. Validate the XML tags in any .xml file in the current directory by opening a terminal window and typing this command at the prompt:

    xmllint --noout --noent --postvalid *.xml

    Any output will tell you what is wrong with the file(s) and you can use that to fix the document. No output means the file is valid.

  8. Check the changes you made by opening a terminal window in the working copy directory and typing this command at the prompt:

    bzr diff
  9. Use the commands in the Bazaar commands resource section below to make additional changes, if needed.

  10. Commit changes to the working copy by opening a terminal window in the working copy directory and typing this command at the prompt:

    bzr commit FILENAME
  11. Enter comments describing the changes into the editor and save and close it.

  12. Publish the changes to Launchpad by opening a terminal window in the working copy directory and typing this command at the prompt, replacing USERNAME with your Launchpad user name and BRANCHNAME with a short word describing the branch:

    bzr push lp:~USERNAME/kubuntu-docs/BRANCHNAME
  13. Log in to Launchpad by opening the https://code.launchpad.net/~ page in your browser.

  14. Select the branch you just published.

  15. Click Propose for Merging.

  16. Type or paste your commit comments into the big text box.

  17. Leave the reviewer box blank.

  18. Open the https://blueprints.launchpad.net/ubuntu/+spec/kubuntu-q-docs page in your browser to access the Launchpad blueprints.

  19. Update the work item by changing its state to the most appropriate state from the list of possible states defined in the WorkItemsHowto wiki page.

Additional resources

Bazaar commands

  • bzr add

    • Add the specified file or subdirectory:

      bzr add FILENAME
  • bzr check

    • Validate working tree structure, branch consistency, and repository history:

      bzr check
  • brz -h or bzr --help

    • Display a brief list of commonly used bzr commands and their descriptions:

      bzr -h
  • bzr log

    • Display the history of commits:

      bzr log
  • bzr mkdir

    • Create a new subdirectory inside your working copy directory:

      bzr mkdir DIRECTORYNAME
  • bzr mv

    • Move or rename a file or subdirectory:

      bzr mv FILENAME
  • bzr revert

    • Undo all uncommitted changes to all files and subdirectories (note that this will also restore deleted files and/or directories):

      bzr revert
    • Undo all uncommitted changes to a specific file or subdirectory (note that this will also restore the file or subdirectory if it was deleted):

      bzr revert FILENAME
  • brz revno

    • Display the current revision number:

      bzr revno
  • bzr rm

    • Delete a file or subdirectory:

      bzr rm FILENAME
  • bzr status

    • Display the status of your working copy directory (this shows changes that need to be committed, files or subdirectories that are not version controlled, files or subdirectories that have conflicts, etc.):

      bzr status

Bazaar conflict resolution

Sometimes changes are made to the parent tree, and if you pull from the parent tree, its changes can conflict with the changes in the child tree. In that case Bazaar will make a suggestion on what to do. For example:

  1. Let's say you have a child tree that contains the APPLE, BANANA, and COCONUT files.

  2. You make some changes to the BANANA file and commit them:

    bzr commit
  3. You do a pull from the parent tree:

    bzr pull
    • You get an error, because the parent tree has changed and conflicts with your child tree:

      bzr: ERROR: These branches have diverged. Try merge.
  4. You look what's in the directory:

    ls
    • You see these three files:

      APPLE BANANA COCONUT
  5. You try the suggestion bzr gave you:

    bzr merge
    • If the merge is simple, bzr will merge the files, preserving the changes from both conflicting files into one new file. Otherwise, you get a warning:

      bzr: WARNING: Text conflict in BANANA
      1 conflicts encountered.
  6. You look what's in the directory now:

    ls
    • You see some new files:

      APPLE BANANA BANANA.BASE BANANA.OTHER BANANA.THIS COCONUT

      There are now four versions of the BANANA file as a result of the conflict:

      • BANANA - This is the file with Bazaar's attempt at merging the conflicting content, with comments showing which parts came from which source.

      • BANANA.BASE - This is the file from the previous revision before it was changed in the parent tree or the child tree.

      • BANANA.OTHER - This is the file you pulled from the parent tree.

      • BANANA.THIS - This is the file from the child tree with your changes.

  7. You examine all four files, and then edit BANANA to contain the content you wish to keep, using content from the other three files, if needed.

  8. You save the changes to the BANANA file.

  9. You tell Bazaar the problem has been resolved:

    bzr resolve BANANA
    • It marks the conflict as having been resolved and deletes the BANANA.BASE, BANANA.OTHER, and BANANA.THIS files for you.

  10. You look what's in the directory now:

    ls
    • You see these three files:

      APPLE BANANA COCONUT
  11. You commit the change to your child tree:

    bzr commit 

If you try to push changes in your child tree to the parent tree and they conflict with changes in the parent tree, do the pull as described above and resolve the conflict in your child tree before pushing to the parent tree.

Contacts in the Kubuntu doc team

DocBook elements

These two KDE web pages contain lists that can be used as rough guidelines for DocBook elements:

DocBook entities

These two files in the libs subdirectory inside your working copy directory offer DocBook entity lists:

  • global.ent - a list of global entities.

  • kde-menus-C.ent - a list of menu entities.

See also

CategoryKubuntuUseful

Kubuntu/SystemDocumentation (last edited 2014-05-08 08:11:31 by apachelogger)