← Back to branch summary

~ubuntu-branches/ubuntu/raring/xiphos/raring

« back to all changes in this revision

Viewing changes to help/Guidelines

  • Committer: Bazaar Package Importer
  • Author(s): Dmitrijs Ledkovs, Jonathan Marsden, Dmitrijs Ledkovs
  • Date: 2010-11-25 21:26:48 UTC
  • mfrom: (2.1.1 experimental)
  • Revision ID: james.westby@ubuntu.com-20101125212648-mc64wvs0nw3xp7bx
Tags: 3.1.4-1
[ Jonathan Marsden ]
* New upstream release 3.1.4
* Removed debian/patch/* since the one patch was included upstream.
* Bumped Standards-Version to 3.9.1 (no changes required).
* debian/README.Debian: Corrected spelling and reworded for clarity.
* debian/control: Add Jonathan Marsden back into Uploaders.

[ Dmitrijs Ledkovs ]
* Added local options dpkg-source to unapply patches and fail on
  upstream source changes (ignoring false positives).
* Added bzr-builddeb hook to generate source-format before build. If you
  are not using bzr-builddeb, you must run "./debian/rules clean" before
  building.
* patches/xul-2.0.patch: bump UPPER_RANGE to allow running against xul20.

Show diffs side-by-side

added added

removed removed

Lines of Context:
help/Guidelines
 
1
--------------------------------------
 
2
Documentation Guidelines
 
3
---------------------------------------
 
4
Welcome to the Xiphos documentation guidelines.
 
5
This document will contain some guidelines for writing/submitting a good patch
 
6
to the Xiphos documentation project.
 
7
 
 
8
Any new features or large scale work should first be discussed on the
 
9
xiphos-developers mailing-list first.  This will ensure the idea fits in the
 
10
direction we wish to take Xiphos, and also that the effort is not
 
11
duplicated.
 
12
 
 
13
-----------------
 
14
General:
 
15
-----------------
 
16
1. Please read the Gnome Documentation Project guidelines. If you would like a copy of it
 
17
in PDF format, please email one of the Documentation developers. 
 
18
 
 
19
2. Whilst editing, you can view your changes by simply going into your working directory and running :
 
20
        " yelp filename.xml". You may have to give the full path, like this: "yelp `pwd`/xiphos.xml" 
 
21
   Also, using xmllint can save a lot of frustration: "xmllint xiphos.xml"
 
22
 
 
23
This also helps with finding errors and debugging. 
 
24
3. Please make sure that you have properly edited xiphos-manual-(lang).omf and Makefile.am.
 
25
-----------------
 
26
Translations
 
27
-----------------
 
28
1. 
 
29
-----------------
 
30
Files:
 
31
----------------
 
32
1. xiphos-manual.xml is the main file to the documentation. All chapter are linked from here. It acts
 
33
as a contents page. The interface section's within Xiphos are broken up into smaller more manageable 
 
34
files which are listed within this file. If a new section is to be added to the manual eg. "Advanced Search dialogs",
 
35
this needs to be mentioned in here. 
 
36
 
 
37
2. Files are broken up into groups of interface categories. If you wish to edit the preferences dialog documentation, just 
 
38
simply edit the "preferences.xml" file.
 
39
 
 
40
------------------
 
41
Screenshots:
 
42
-------------------
 
43
1. screenshots will only be accepted if it is in the "Simple" theme. It can be
 
44
accessed by going:
 
45
 
 
46
        Applications -> Desktop Preferences -> Theme
 
47
        or 
 
48
        by simply running the command "gnome-theme-manager" in the terminal.
 
49
 
 
50
2.Please use discretion about image sizes. This includes file size and images size ( length
 
51
and height). While there is no rule or standard to how big the image must be, visibility of the
 
52
screenshot and visibility within "Yelp" is the main priority. We don't want to user to scroll horizontally
 
53
just to view a screenshot. I normally keep my screenshot width at a maximum of 600 pixels.
 
54
 
 
55
3.file naming will be done with the prefix of the interface ( eg. preferences, underscore, interface subsection ( eg. font-color ) 
 
56
eg. " preferences_fontscolor.png"
 
57
NOTE: please use lower-case.
 
58
 
 
59
------------------
 
60
Windows Help files
 
61
-----------------
 
62
The DocBook copies are the master copy. Any alterations on the Windows
 
63
helpfiles should only be done if the addition is absolutely and definitely
 
64
Windows specific about a Windows subject only. If it is advise about the way
 
65
a common problem is solved in Windows (and a similar piece of advice should
 
66
be given to Unix/Linux users, please add your addition to Docbook.
 
67
 
 
68
The Windows htmlhelp files  should regularly get updated after serious commits. 
 
69
To create a Windows Help file you require two steps:
 
70
 
 
71
1) process the docbook files with an XSL1.0 processor - e.g. Saxon 6.5.5
 
72
(not the newer Saxon9 versions) and the htmlhelp stylesheet (available in
 
73
docbook-xsl) 
 
74
 
 
75
 java -jar saxon.jar xiphos.xml htmlhelp.xsl
 
76
 
 
77
2) create the CHM file out of the intermediate source by using htmlhelp.exe
 
78
on a Windows system (obtainable from Microsoft). 
 
79
 
 
80
 
 
81