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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
|
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
<!ENTITY % sgml.features "IGNORE">
<!ENTITY % xml.features "INCLUDE">
<!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod">
%DOCBOOK_ENTS;
]>
<chapter conformance="217" version="5.0" xml:id="chap-Publican-Users_Guide-Building_a_website_with_Publican" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<info>
<title>Building a website with Publican</title>
</info>
<para>
<application>Publican</application> not only builds documents for publication but can build and manage a documentation website as well. For a suite of documents that you maintain by yourself, you can use <application>Publican</application> to build a site on your local system; you can then upload the site to a webserver by whatever means you choose. This approach does not scale well, however, so for team-based documentation projects, <application>Publican</application> can generate RPM packages of documentation to install on the webserver. To install <application>Publican</application>-generated RPM packages on a webserver, <application>Publican</application> (version 2.1 or higher) and <application>rpm</application> must be installed on the server. If you build and maintain the website on a workstation and upload it to a webserver for publication, <application>Publican</application> and <application>rpm</application> do not need to be installed on the webserver.
</para>
<para>
The websites that <application>Publican</application> creates consist of four parts: the website structure, a home page, product and version description pages, and the documents published on the site. The website structure itself consists of:
</para>
<itemizedlist>
<listitem>
<para>
a configuration file.
</para>
</listitem>
<listitem>
<para>
an SQLite database file.
</para>
</listitem>
<listitem>
<para>
a subdirectory for the published documents, which contains:
</para>
<itemizedlist>
<listitem>
<para>
<filename>index.html</filename> — an index page that redirects to localized versions of a home page for the site.
</para>
</listitem>
<listitem>
<para>
<filename>interactive.css</filename> — a CSS stylesheet that contains styles for the navigation menu.
</para>
</listitem>
<listitem>
<para>
<filename>opds.xml</filename> — an Open Publication Distribution System (OPDS) catalog to allow compliant eBook readers to find EPUB documents on your site easily.
</para>
</listitem>
<listitem>
<para>
<filename>Sitemap</filename> — A Sitemap is a list of the URLs from your website and metadata about them, like update history, change frequency, and importance relative to other URLs in the site. A Sitemap can be supplied to many major search engines, where it is used to help their crawlers index your site more intelligently. A Sitemap does not guarantee that your site will be ranked higher in search results. However, it does help search engines to return the most relevant results from your website in response to user queries. For more information on Sitemaps, visit <link xlink:href="http://www.sitemaps.org/" xmlns:xlink="http://www.w3.org/1999/xlink">sitemaps.org</link>.
</para>
</listitem>
<listitem>
<para>
<filename>site_overrides.css</filename> — a CSS stylesheet that overrides the styles contained in <filename>interactive.css</filename> to provide site-specific styles. This file is not created by the site creation process, but must be added manually later, or supplied by the site <firstterm>home page</firstterm>.
</para>
</listitem>
<listitem>
<para>
<filename>default.js</filename> — a JavaScript script that directs visitors to localized content based on the locale set in their browser and which controls the presentation of the navigation menu.
</para>
</listitem>
<listitem>
<para>
subdirectories for each language in which you publish. Initially, this contains <filename>opds.xml</filename> and <filename>toc.html</filename>. Later it also contains <filename>opds-<replaceable>product</replaceable>.xml</filename>:
</para>
<itemizedlist>
<listitem>
<para>
<filename>opds.xml</filename> — an OPDS catalog of EPUB documents in this language.
</para>
</listitem>
<listitem>
<para>
<filename>opds-<replaceable>product</replaceable>.xml</filename> — an OPDS catalog of EPUB documents for each product for which you publish documentation in this language. Within each product catalog, documentation is divided into <tag><category></tag>s for different versions of the same product.
</para>
</listitem>
<listitem>
<para>
<filename>toc.html</filename> — the table of contents for that language, initially without links to any documents.
</para>
</listitem>
<listitem>
<para>
A subdirectory for each product for which you publish documentation in this language.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>
Optionally, the site structure might also include a <firstterm>dump file</firstterm> — an XML file that provides complete site content details for delivery of other services, such as web feeds or customised search pages. The site structure might also contain a zipped version of the dump file. Refer to <xref linkend="sect-Publican-Users_Guide-Building_a_website_with_Publican-Building_a_website_manually" /> and <xref linkend="sect-Publican-Users_Guide-Building_a_website_with_Publican-Building_a_website_using_RPM_packages" /> for details of creating a dump file, and to <xref linkend="appe-Publican-Users_Guide-Contents_of_the_website_dump_file" /> for a description of the dump file contents.
</para>
<section conformance="218" xml:id="sect-Publican-Users_Guide-Building_a_website_with_Publican-Building_a_website_manually">
<info>
<title>Building a website manually</title>
</info>
<xi:include href="Websites_structure_manual.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Websites_homepage_manual.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Websites_product_version_manual.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Websites_documents_manual.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</section>
<section conformance="219" xml:id="sect-Publican-Users_Guide-Building_a_website_with_Publican-Building_a_website_using_RPM_packages">
<info>
<title>Building a website using RPM packages</title>
</info>
<xi:include href="Websites_structure_rpm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Websites_homepage_rpm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Websites_product_version_rpm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Websites_documents_rpm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</section>
<section conformance="220" xml:id="sect-Publican-Users_Guide-Building_a_website_with_Publican-Submitting_Your_Sitemap_to_Search_Engines">
<info>
<title>Submitting Your Sitemap to Search Engines</title>
</info>
<para>
A Publican website includes an XML Sitemap file. The Sitemap can be submitted to many major search engines, in order to help them index your website more intelligently and thoroughly. Each search engine has its own submission procedure. This section includes documentation on how to submit a Sitemap to Google and Bing.
</para>
<section conformance="221" xml:id="sect-Publican-Users_Guide-Submitting_Your_Sitemap_to_Search_Engines-Submitting_Your_Sitemap_to_Google.">
<info>
<title>Submitting Your Sitemap to Google.</title>
</info>
<procedure conformance="222" xml:id="proc-Publican-Users_Guide-Submitting_Your_Sitemap_to_Google.-To_Submit_Your_Sitemap_to_Google">
<title>To Submit Your Sitemap to Google:</title>
<step>
<para>
Sign up for a Google account at <link xlink:href="http://www.google.com/webmasters/tools/home" xmlns:xlink="http://www.w3.org/1999/xlink">Google Webmaster Tools</link>. If you already have a Google account, you can use it.
</para>
</step>
<step>
<para>
Sign in to your Google Webmaster Tools account at this URL: <link xlink:href="http://www.google.com/webmasters/tools/home" xmlns:xlink="http://www.w3.org/1999/xlink">http://www.google.com/webmasters/tools/home</link>.
</para>
</step>
<step>
<para>
First you must verify you are the owner of your Publican site. Click the <guibutton>Add A Site</guibutton> button.
</para>
</step>
<step>
<para>
A dialog box is displayed for you to <guilabel>Add a site</guilabel> with. Enter the URL of your Publican site in the text entry field and click <guibutton>Continue</guibutton>.
</para>
</step>
<step>
<para>
Follow the instructions that display and upload the HTML file that Google provides to the document root of your website.
</para>
</step>
<step>
<para>
When you have confirmed that the provided HTML file has been uploaded to the required location by accessing it in a web browser, click the <guibutton>Verify</guibutton> button.
</para>
</step>
<step>
<para>
When you have successfully verified the ownership of your Publican website to Google, return to the Webmaster Tools home page. Your Publican site is listed. Click on it.
</para>
</step>
<step>
<para>
You are taken to the Webmaster Tools configuration page for your Publican site. On the left side of the page there is a menu. Click on the <guilabel>Site configuration</guilabel> menu entry to expand it. Its expanded contents includes a <guilabel>Sitemaps</guilabel> entry. Click it.
</para>
</step>
<step>
<para>
You are taken to a Sitemap submission page. Click the <guibutton>Submit a Sitemap</guibutton> button.
</para>
</step>
<step>
<para>
A text entry field displays, including the base URL of your Publican site, with room to enter the URL of your Sitemap XML file. Enter its location and click the <guibutton>Submit Sitemap</guibutton> button. The details of the Sitemap are displayed in a table.
</para>
</step>
</procedure>
<formalpara conformance="256" xml:id="form-Publican-Users_Guide-To_Submit_Your_Sitemap_to_Google-Result">
<title>Result</title>
<para>
The Sitemap for your Publican site has been successfully submitted to Google.
</para>
</formalpara>
</section>
<section conformance="223" xml:id="sect-Publican-Users_Guide-Submitting_Your_Sitemap_to_Search_Engines-Submitting_Your_Sitemap_to_Bing.">
<info>
<title>Submitting Your Sitemap to Bing.</title>
</info>
<procedure conformance="224" xml:id="proc-Publican-Users_Guide-Submitting_Your_Sitemap_to_Bing.-To_Submit_Your_Sitemap_to_Bing">
<title>To Submit Your Sitemap to Bing:</title>
<step>
<para>
Sign up for a Bing Webmaster Tools account at <link xlink:href="http://www.bing.com/toolbox/webmaster/" xmlns:xlink="http://www.w3.org/1999/xlink">Bing Webmaster Tools</link>. If you already have a Windows LiveID account, you can use it.
</para>
</step>
<step>
<para>
Sign in to your Bing Webmaster Tools account at this URL: <link xlink:href="http://www.bing.com/toolbox/webmaster/" xmlns:xlink="http://www.w3.org/1999/xlink">http://www.bing.com/toolbox/webmaster/</link>.
</para>
</step>
<step>
<para>
Click the <guibutton>Add Site</guibutton> button.
</para>
</step>
<step>
<para>
The <guilabel>Add Site</guilabel> dialog box is displayed. Enter the URL of your Publican site in the text entry field and click <guibutton>Submit</guibutton>.
</para>
</step>
<step>
<para>
The <guilabel>Verify Ownership</guilabel> dialog displays, with three options. Follow the instructions given when the <guilabel>Option 1: Place an XML file on your web server</guilabel> has been expanded. Upload the <systemitem>BingSiteAuth.xml</systemitem> file that Bing provides to the document root of your website.
</para>
</step>
<step>
<para>
When you have confirmed that the provided <systemitem>BingSiteAuth.xml</systemitem> file has been uploaded to the required location by accessing it in a web browser, click the <guibutton>Verify</guibutton> button.
</para>
</step>
<step>
<para>
When you have successfully verified your ownership of your Publican website to Bing, return to the Bing Webmaster Tools home page. Your Publican site is listed. Click on it.
</para>
</step>
<step>
<para>
Select the <guibutton>Crawl</guibutton> tab.
</para>
</step>
<step>
<para>
Select <guilabel>Sitemaps</guilabel> and then <guilabel>Add Feed</guilabel>.
</para>
</step>
<step>
<para>
The <guilabel>Add Feed</guilabel> dialog displays. Enter the URL of your Sitemap file and click <guibutton>Submit</guibutton>. The details of the Sitemap are displayed.
</para>
</step>
</procedure>
<formalpara conformance="257" xml:id="form-Publican-Users_Guide-To_Submit_Your_Sitemap_to_Bing-Result">
<title>Result:</title>
<para>
The Sitemap for your Publican site has been successfully submitted to Bing.
</para>
</formalpara>
</section>
</section>
</chapter>
|
