~dpm/help-app/new-content-and-fixes

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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
Welcome to Help for Ubuntu devices!
===================================

What are we doing here?
-----------------------

In a conversation amongst Ubuntu phone enthusiasts, we decided we wanted to
create a good way in which we can aggregate information, tips and tricks and
suggestions for using Ubuntu devices (like the phone or a tablet) easily.

The end result being new Ubuntu users who can

 * find out more about how to use their phone
 * quickly be more productive
 * find new things
 * get started easily because the information is available in their language

Thanks a lot for your interest in helping out!


How does this all work?
-----------------------

Our work-flow is a bit special, so bear with us for a while. If you just want
to start adding content, skip this section. The sections below should 
probably be enough for that.

We had a couple of requirements when we started this project:

 * easy to add/modify content (we decided to use Markdown)
 * easy to translate content (we decided to use Launchpad)
 * easy to create different builds (one for the phone, one for an online
   site, like *.ubuntu.com)

On the way to implementing all of the above, we settled on a mixture of
pelican and po4a on the content side, the Ubuntu HTML5 UI toolkit and
the Ubuntu Web Guidelines on the display side.

 * po4a is used to extract translatable messages from the Markdown 
   content, so that we can get .pot and .po files which are understood by 
   Launchpad. We also use po4a to generate translated Markdown files.
 * pelican takes care of generating HTML from the translated Markdown
   files. It can build into different output directories, using different
   themes, which is very handy in our case.
 * The Ubuntu HTML5 UI toolkit is used for the phone app.
 * The Ubuntu Web Guidelines for the build which we will put up on an
   Ubuntu site very soon.


Directory structure
-------------------


├── app                 ← Everything related to the devices app.
│   └── www             ← The viewable content of the app.
└── edit-here
    ├── content
    │   └── pages       ← Here is the place to edit the content.
    ├── po              ← Translations.
    └── themes          ← Themes files, both templates and css/js.
        ├── phone       ← Phone/device app theme.
        └── web         ← Online build (.ubuntu.com) theme.


Prerequisites
-------------

Before you get started, run:

  sudo apt install python-pelican po4a make bzr \
	ubuntu-html5-ui-toolkit python3-polib

This will install the necessary files, so you can build the app or web build
locally and check if your changes actually make sense and look and work well.


Editing
-------

This app is structured in a very simple way. All the content is and all your
edits happen in

	./edit-here/content/pages/

The markup for the text is Markdown, which is very easy to learn. Just have 
a look at http://daringfireball.net/projects/markdown/ and some of the 
existing files to get started.

Once you're happy with your edits, change to the top-level directory and run

	make html

This will also generate translated pages.

You can find the updated HTML in ./app/www/. For instance, you can browse 
the site in firefox with

firefox app/www/index.html


Creating a click
----------------

To create a click package (for example, if you want to test it on your
device), just run

	make click

in the top-level directory.


Publishing it on the web
------------------------

We also want to publish this information on the web. To start a 'web' build
of the content, just run

	make web

Find the resulting files in ./web in the top-level directory.

We plan to make use of 
http://www.w3.org/International/questions/qa-apache-lang-neg for publishing
this on the web.


Code, bugs, etc.
----------------

To file bugs, or view/submit merge proposals, simply use this project in
Launchpad:

	https://launchpad.net/ubuntu-devices-help

To update the .pot file, simply run the following command in the edit-here/
directory:

	make update-pot

If you want to get help with the app or anything else, ask the fine folks
in #ubuntu-app-devel - for example dholbach, balloons or dpm.

Thanks a lot for helping out!