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
|
Manual Guidelines
=================
Welcome to the Xiphos Manual guidelines.
This document will contain some guidelines for writing/submitting a good patch
to the Xiphos Manual project.
Any new features or large scale work should first be discussed on the
[xiphos-devel](xiphos-users@crosswire.org) 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:
--------
The Xiphos Manual is written in [Mallard Markup language](http://projectmallard.org)
To write Mallard Documentation, you should have some familiarity with markup
languages such as HTML and XML.
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.
* https://wiki.gnome.org/DocumentationProject
Other resources:
* http://write.flossmanuals.net/introduction-to-mallard/editorial-comments/
* http://blogs.gnome.org/shaunm/files/2012/01/mallardcheatsheet.png
2. Whilst editing, you can view your changes by simply going into your working
directory and running : " yelp index.page". You may have to give the full path,
like this: "yelp `pwd`/index.page"
Also, using yelp-check can save a lot of frustration:
"yelp-check validate *.page"
This also helps with finding errors and debugging.
Files:
------
1. A Mallard help document is composed of several independent pages. Each page
is kept in a separate XML file with the file extension .page.
Every Mallard document requires a front page to serve as an overarching index,
whose filename is index.page.
2. By default, Mallard will order all topic pages alphabetically on the index
page. Guide pages can be nested within other guide pages to create organization
on the index page.
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.
Widows Help files:
------------------
The Mallard pages 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 Mallard
Pages.
|
