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