Desktop Help Tasks
This page holds a list of tasks to do with the desktop help. This is the set of help files which are relevant to the GNOME desktop as a whole. For more information about getting involved, see here.
Resources and References
Tasks for 3.14
Tasks are listed in order of priority.
The status menu has had a whole bunch of stuff added to it for 3.12, such as bluetooth and location. This may change between the UI freeze and the release.
Pages that talk about airport mode, see bug https://bugzilla.gnome.org/show_bug.cgi?id=709128
- User types (Standard/Administrator)
Other small tasks
- Review all net-* pages, these are very popular
- Document search providers
Document what a home directory is, and replace references to <file>Home</file witha link to it
- Document how to remove a saved fingerprint (session-fingerprint)
- Add privacy-location and document turning off geolocation (Geoclue)
To update list, run 'yelp-check status --only outdated gnome-help/C/*.page'
Review -> Candidate/Outdated
Check language and instructions. Sometimes, 'review' pages need more content.
To update list, run 'yelp-check status --only review gnome-help/C/*.page'
Research this bug. Either write up the process of installing the fonts using nautilus and attach a patch to the bug, or state on the bug what the situation is if it is no longer possible to do this.
Contributing to the Desktop Help
1) install git
2) setup git:
$ git config --global user.email firstname.lastname@example.org
$ git config --global user.name "Your Name"
3) Get the latest version of the gnome-user-docs from the git repository:
$ git clone git://git.gnome.org/gnome-user-docs
4) Go into the directory which contains the Mallard files (.page files) by typing:
$ cd gnome-user-docs/gnome-help/C/
To view the current state of the desktop help from the index page type:
$ yelp index.page
Editing existing pages
1) To view the Mallard source and/or make changes to existing pages you can use a text editor (like Gedit):
$ gedit <pagename>
* Do not include the angle brackets.
* Make your edits.
2) To view your changes using the help viewer:
$ yelp <pagename>
If the page doesn't show up in yelp, there may be a problem with the Mallard markup. If this happens, check the terminal output for errors (the error and line number of the error will be output to the terminal).
Creating new pages
1) install yelp-tools
2) To create a new topic page name <newtopic> with <Title> type:
$ yelp-new task <taskname> "<Page Title>"
* Do not include the angle brackets. <taskname> becomes the name of the .page file.
3) Add the new page to git:
$ git add <newpagename>
* Make sure you add each new page you create. If you forget, it will not be included in the .patch file, and your hard work may get lost.
You will notice the new page already has your name inserted as the author. Delete any of the boiler-plate markup or paragraphs which you do not need, and write, write, write.
These pre-commit checks will save the person reviewing your patch time and help you get your patch committed faster. The first is just a visual check, the second requires you to have yelp-tools installed, while the last is the most difficult as it depends on your having some other software installed and need to be able to understand output from a terminal.
Check that you have updated the <revision> tag and added yourself to the credits
Use yelp-tools to 'yelp-check validate' the pages and 'yelp-check links' to check that xref (internal) links are valid
Build gnome-user-docs to make sure the gnome-help/Makefile.am is correct
- Open a terminal
'cd' into the gnome-user-docs directory (for example, 'cd work/gnome-user-docs')
- Check for errors in the output
Create a .patch file
1) When you are happy with your topics, in the Terminal, type
$ git commit -a -m "A commit message goes here explaining what your changes are. If your changes fix a bug, include the bug #."
The commit message should be less than 50 characters, but informative.
2) Once your changes are commited type:
$ git format-patch HEAD^
This will create a .patch file in your current directory (the filename will start with 0001-)
Attach this file to a bug in Bugzilla. If you are fixing a current bug filed Bugzilla, attach the file to that bug. If this .patch is a new change or a new page, you will need to create a new bug. If you do not have a bugzilla account, see section E. below.
Attach your patch to the bug asking for a review.
NOTE: You can make many commits, and then make all the patch files at the same time. So for example, if you made 3 commits, you could then createall 3 patches at the same time by typing:
$ git format-patch HEAD^^^
Your 3 patch files will then be consecutively numbered.
If you are working along and want to see a log of the commits, you can type:
$ git log
Create a Bugzilla account and file a new bug.
1) This page has information about how to create an account on Bugzilla, as well as how to create a new bug against the gnome-user-docs.
Once your patch is attached to a bug. a member of the Gnome Documentation Team will get back to you with comments, suggestions and edits, and we can work together on finalising the topics you wrote. They will then be added to the Desktop Help.