[fedora-cookbook] master: an admonition about scope (6594a82)
by Pete Travis
Repository : http://git.fedorahosted.org/cgit/docs/fedora-cookbook.git
On branch : master
>---------------------------------------------------------------
commit 6594a82e0db435bdc27278016e7c55072433af25
Author: Pete Travis <immanetize(a)fedoraproject.org>
Date: Sat Mar 22 00:27:43 2014 -0400
an admonition about scope
>---------------------------------------------------------------
en-US/Documenting_Fedora/writing_recipes.xml | 13 ++++++++++++-
1 files changed, 12 insertions(+), 1 deletions(-)
diff --git a/en-US/Documenting_Fedora/writing_recipes.xml b/en-US/Documenting_Fedora/writing_recipes.xml
index e6653d2..58c2c87 100644
--- a/en-US/Documenting_Fedora/writing_recipes.xml
+++ b/en-US/Documenting_Fedora/writing_recipes.xml
@@ -56,7 +56,18 @@
<step>
<para>
Choose a topic. The focus of the article should be clear, and you should be able to achieve the goal in a short series of steps. If the process is complex, consider splitting into a series of smaller articles.
- </para></step>
+ </para>
+ <important>
+ <title>Write about Fedora!</title>
+ <para>
+ Fedora Documentation should be only cover capabilities that Fedora can provide. Fedora is about free software, and the docs should be as free as the code.
+ </para>
+ <para>
+ Submissions that require software not available in Fedora should be avoided. Tutorials that require software that is <ulink url="https://fedoraproject.org/wiki/Forbidden_itemshttps://fedoraproject.org/w...">not permissible</ulink> for Fedora cannot be accepted.
+ </para>
+ </important>
+
+ </step>
<step>
<para>
Download a template from <ulink url="https://git.fedorahosted.org/cgit/docs/fedora-cookbook.git/tree/en-US/exa...">the repository</ulink> maintained by the Fedora Docs team. Choose the format you like, then click <guilabel>plain</guilabel> to get it in a format you can cut and paste into an editor.
10 years, 2 months
[documentation-guide] Minor edits for the sake of consistency.
by jhradile
commit 8b97717e2c1e12a0edb56b04a49f663d3a259b4d
Author: Jaromir Hradilek <jhradile(a)redhat.com>
Date: Sat Mar 22 04:55:01 2014 +0100
Minor edits for the sake of consistency.
en-US/publican.xml | 43 ++++++++++++++++++++++++-------------------
1 files changed, 24 insertions(+), 19 deletions(-)
---
diff --git a/en-US/publican.xml b/en-US/publican.xml
index 1469b33..15e6cc5 100644
--- a/en-US/publican.xml
+++ b/en-US/publican.xml
@@ -21,7 +21,7 @@
</para>
<synopsis><command>yum</command> <option>install</option> <option>publican</option> <option>publican-fedora</option></synopsis>
<para>
- By default, only the <systemitem>common</systemitem> brand is installed with the <package>publican</package> package. There are many brands in Fedora repositories, such as <systemitem>oVirt</systemitem> (<package>publican-ovirt</package>), <systemitem>JBoss</systemitem> (<package>publican-jboss</package>), or <systemitem>genome</systemitem> (<package>publican-genome</package>). For a full list of available brands, refer to the <citetitle pubwork="book">Publican Users' Guide</citetitle>.
+ By default, only the <systemitem>common</systemitem> brand is installed with the <package>publican</package> package. There are many brands in Fedora repositories, such as <systemitem>oVirt</systemitem> (<package>publican-ovirt</package>), <systemitem>JBoss</systemitem> (<package>publican-jboss</package>), or <systemitem>genome</systemitem> (<package>publican-genome</package>).
</para>
</section>
<section id="sect-publican-creating">
@@ -31,17 +31,20 @@
</para>
<para>
To create a new book, type the following at a shell prompt:
- <synopsis><command>publican</command> <option>create</option> <option>--type</option> <option>book</option> <option>--name</option> "<replaceable>Document Name</replaceable>" <option>--brand</option> <replaceable>brand</replaceable></synopsis>
-
- where <replaceable>Document Name</replaceable> is the document title and <replaceable>brand</replaceable> is the brand you want to use (this is typically <literal>fedora</literal>). Similarly, run the following command to create an article:
- <synopsis><command>publican</command> <option>create</option> <option>--type</option> <option>article</option> <option>--name</option> "<replaceable>Document Name</replaceable>" <option>--brand</option> <replaceable>brand</replaceable></synopsis>
- Additionally, you can specify the <option>--lang</option> option followed by a language code (such as <literal>pt-BR</literal> or <literal>cs-CZ</literal>) to write the book in a different language than English.
+ </para>
+ <synopsis><command>publican</command> <option>create</option> <option>--type</option> <option>book</option> <option>--name</option> "<replaceable>Document Name</replaceable>" <option>--brand</option> <replaceable>brand</replaceable></synopsis>
+ <para>
+ Replace <replaceable>Document Name</replaceable> with the document title and <replaceable>brand</replaceable> with the brand you want to use (typically <literal>fedora</literal>). Similarly, to create a new article, run the following command:
+ </para>
+ <synopsis><command>publican</command> <option>create</option> <option>--type</option> <option>article</option> <option>--name</option> "<replaceable>Document Name</replaceable>" <option>--brand</option> <replaceable>brand</replaceable></synopsis>
+ <para>
+ Additionally, you can specify the <option>--lang</option> option followed by a language code (such as <literal>pt-BR</literal> or <literal>cs-CZ</literal>) to write the book in a language different than English.
</para>
<para>
The <command>publican create</command> command creates a new directory named <replaceable>Document_Name</replaceable>. This directory contains the <filename>publican.cfg</filename> configuration file and another directory named after the language code (that is, <filename class="directory">en-US/</filename> by default), which contains boilerplate files as described in <xref linkend="tabl-publican-creating" />.
</para>
<table id="tabl-publican-creating">
- <title>Files created by Publican</title>
+ <title>Files Created By Publican</title>
<tgroup cols="3">
<colspec colname="Book" colnum="1" colwidth="25*" />
<colspec colname="Article" colnum="2" colwidth="25*" />
@@ -148,25 +151,27 @@
</para>
<synopsis><command>publican build --langs <replaceable>languages</replaceable> --formats test</command></synopsis>
<para>
- Replace <replaceable>languages</replaceable> with a comma-separated list of language codes. Note that when you build a document as described in <xref linkend="sect-publican-building" />, Publican automatically validates it for you.
+ Replace <replaceable>languages</replaceable> with a comma-separated list of language codes (such as <literal>en-US</literal> or <literal>cs-CZ</literal>). Note that when you build a document as described in <xref linkend="sect-publican-building" />, Publican automatically validates it for you.
</para>
</section>
<section id="sect-publican-building">
<title>Building a Document</title>
<para>
To build a document in order to review it, use the following command:
- <synopsis><command>publican</command> <option>build</option> <option>--langs</option> <replaceable>languages</replaceable> <option>--formats</option> <replaceable>formats</replaceable></synopsis>
- where <replaceable>languages</replaceable> is a comma-separated list of language codes and <replaceable>formats</replaceable> is a comma-separated list of file formats you want to build as described in <xref linkend="tabl-publican-building" />.
+ </para>
+ <synopsis><command>publican</command> <option>build</option> <option>--langs</option> <replaceable>languages</replaceable> <option>--formats</option> <replaceable>formats</replaceable></synopsis>
+ <para>
+ Replace <replaceable>languages</replaceable> with a comma-separated list of language codes (such as <literal>en-US</literal> or <literal>cs-CZ</literal>) and <replaceable>formats</replaceable> with a comma-separated list of file formats as described in <xref linkend="tabl-publican-building" />.
</para>
<para>
- By default, the <command>publican build</command> command stores created files in the <filename class="directory">tmp/</filename> directory where you can review the output. To build a final version of the document, add the <option>--publish</option> option as follows:
+ By default, the <command>publican build</command> command stores the created files in the <filename class="directory">tmp/</filename> directory where you can review the output. To build a final version of the document, add the <option>--publish</option> option as follows:
</para>
<synopsis><command>publican</command> <option>build</option> <option>--publish</option> <option>--langs</option> <replaceable>languages</replaceable> <option>--formats</option> <replaceable>formats</replaceable></synopsis>
<para>
- This places the generated files in the <filename class="directory">publish/</filename> directory. If you intend to publish the document at the <ulink url="http://docs.fedoraproject.org" /> website, use also the <option>--embedtoc</option> option. For detailed information on how to publish a document on the Fedora Documentation Project website, refer to <xref linkend="sect-publican-publishing" />.
+ This places the generated files in the <filename class="directory">publish/</filename> directory. For information on how to publish your document on the Fedora Documentation website, see <xref linkend="sect-publican-publishing" />.
</para>
<table id="tabl-publican-building">
- <title>Available target formats</title>
+ <title>Available Target Formats</title>
<tgroup cols="2">
<colspec colname="Format" colnum="1" colwidth="25*" />
<colspec colname="Description" colnum="2" colwidth="75*" />
@@ -262,15 +267,15 @@
<section id="sect-publican-publishing-adding">
<title>Adding a New Document</title>
<para>
- In order to publish an entirely new document or a new major version of an already published document on the <ulink url="http://docs.fedoraproject.org/">Fedora Documentation</ulink> website, <ulink url="https://fedorahosted.org/rel-eng/newticket">open a support ticket with Fedora Release Engineering</ulink> and request addition of the relevant RPM package name to the <systemitem>el6-docs</systemitem> repository. RPM package names of document created by Publican have the following format:
+ In order to publish an entirely new document or a new major version of an already published document on the <ulink url="http://docs.fedoraproject.org/">Fedora Documentation</ulink> website, <ulink url="https://fedorahosted.org/rel-eng/newticket">open a support ticket with Fedora Release Engineering</ulink> and request addition of the relevant RPM package name (for example <literal>Fedora-Security_Guide-19-web-en-US</literal>) to the <systemitem>el6-docs</systemitem> repository. Package names of documents created by Publican have the following format:
</para>
<synopsis><replaceable>product_name</replaceable>-<replaceable>document_title</replaceable>-<replaceable>product_number</replaceable>-web-<replaceable>language</replaceable></synopsis>
<para>
- To determine the exact package name, you can run the following command in the main directory of your document:
+ To help you determine the correct package name for your document, you can run the following command in the main directory of your document:
</para>
<synopsis><command>publican package --lang <replaceable>language</replaceable></command></synopsis>
<para>
- Replace <replaceable>language</replaceable> with a selected language code. This command packages your document as a source RPM (SRPM) and prints the absolute path to this package to standard output.
+ Replace <replaceable>language</replaceable> with a selected language code (such as <literal>en-US</literal> or <literal>cs-CZ</literal>). This command packages your document as a source RPM (SRPM) and prints the absolute path to this package to standard output.
</para>
</section>
<section id="sect-publican-publishing-updating">
@@ -293,7 +298,7 @@
<command>--firstname <replaceable>first_name</replaceable> --surname <replaceable>surname</replaceable> --email <replaceable>email</replaceable> \</command>
<command>--member "<replaceable>description</replaceable>"</command></screen>
<para>
- Replace <replaceable>language</replaceable> with a selected language code, <replaceable>first_name</replaceable> with your given name, <replaceable>surname</replaceable> with your surname, <replaceable>email</replaceable> with your email address, and <replaceable>description</replaceable> with a brief description of your changes.
+ Replace <replaceable>language</replaceable> with a selected language code (such as <literal>en-US</literal> or <literal>cs-CZ</literal>), <replaceable>first_name</replaceable> with your given name, <replaceable>surname</replaceable> with your surname, <replaceable>email</replaceable> with your email address, and <replaceable>description</replaceable> with a brief description of your changes.
</para>
</step>
<step>
@@ -302,7 +307,7 @@
</para>
<synopsis><command>publican package --lang <replaceable>language</replaceable></command></synopsis>
<para>
- Replace <replaceable>language</replaceable> with a selected language code. This command stores the newly created SRPM package in the <filename class="directory">tmp/rpm/</filename> directory and prints the absolute path to this file to standard output. If you intend to publish your document in more than one language, repeat this step with a different language code.
+ Replace <replaceable>language</replaceable> with a selected language code (such as <literal>en-US</literal> or <literal>cs-CZ</literal>). This command stores the newly created SRPM package in the <filename class="directory">tmp/rpm/</filename> directory and prints the absolute path to this file to standard output. If you intend to publish your document in more than one language, repeat this step with a different language code.
</para>
</step>
<step>
@@ -311,7 +316,7 @@
</para>
<synopsis><command>koji build el6-docs <replaceable>package_name</replaceable></command></synopsis>
<para>
- Replace <replaceable>package_name</replaceable> with a path to the SRPM package.
+ Replace <replaceable>package_name</replaceable> with a path to the SRPM package (for example, <literal>tmp/rpm/Fedora-Security_Guide-19-web-en-US-19.1-1.el6.src.rpm</literal>).
</para>
</step>
</procedure>
10 years, 2 months
[documentation-guide] Documented how to validate a document.
by jhradile
commit aa9c6b3e04e727057818951125580bfc0a918ac6
Author: Jaromir Hradilek <jhradile(a)redhat.com>
Date: Sat Mar 22 04:27:56 2014 +0100
Documented how to validate a document.
en-US/publican.xml | 8 +++++++-
1 files changed, 7 insertions(+), 1 deletions(-)
---
diff --git a/en-US/publican.xml b/en-US/publican.xml
index 335d01f..1469b33 100644
--- a/en-US/publican.xml
+++ b/en-US/publican.xml
@@ -143,7 +143,13 @@
</section>
<section id="sect-publican-validating">
<title>Validating a Document</title>
- <remark>Hic sunt leones.</remark>
+ <para>
+ To check your document and ensure that all source files are valid DocBook XML, type the following at a shell prompt:
+ </para>
+ <synopsis><command>publican build --langs <replaceable>languages</replaceable> --formats test</command></synopsis>
+ <para>
+ Replace <replaceable>languages</replaceable> with a comma-separated list of language codes. Note that when you build a document as described in <xref linkend="sect-publican-building" />, Publican automatically validates it for you.
+ </para>
</section>
<section id="sect-publican-building">
<title>Building a Document</title>
10 years, 2 months
[documentation-guide] Documented how to add a new document to Koji.
by jhradile
commit e77ee57e599920df9197a6bc19d1acc2e31c9a77
Author: Jaromir Hradilek <jhradile(a)redhat.com>
Date: Sat Mar 22 04:13:31 2014 +0100
Documented how to add a new document to Koji.
en-US/publican.xml | 12 +++++++++++-
1 files changed, 11 insertions(+), 1 deletions(-)
---
diff --git a/en-US/publican.xml b/en-US/publican.xml
index c752590..335d01f 100644
--- a/en-US/publican.xml
+++ b/en-US/publican.xml
@@ -255,7 +255,17 @@
<title>Publishing a Document</title>
<section id="sect-publican-publishing-adding">
<title>Adding a New Document</title>
- <remark>Hic sunt leones...</remark>
+ <para>
+ In order to publish an entirely new document or a new major version of an already published document on the <ulink url="http://docs.fedoraproject.org/">Fedora Documentation</ulink> website, <ulink url="https://fedorahosted.org/rel-eng/newticket">open a support ticket with Fedora Release Engineering</ulink> and request addition of the relevant RPM package name to the <systemitem>el6-docs</systemitem> repository. RPM package names of document created by Publican have the following format:
+ </para>
+ <synopsis><replaceable>product_name</replaceable>-<replaceable>document_title</replaceable>-<replaceable>product_number</replaceable>-web-<replaceable>language</replaceable></synopsis>
+ <para>
+ To determine the exact package name, you can run the following command in the main directory of your document:
+ </para>
+ <synopsis><command>publican package --lang <replaceable>language</replaceable></command></synopsis>
+ <para>
+ Replace <replaceable>language</replaceable> with a selected language code. This command packages your document as a source RPM (SRPM) and prints the absolute path to this package to standard output.
+ </para>
</section>
<section id="sect-publican-publishing-updating">
<title>Updating a Document</title>
10 years, 2 months
[documentation-guide] Documented how to publish a document using Koji.
by jhradile
commit df44444732abce9c24549c7e57642f0652bf34ee
Author: Jaromir Hradilek <jhradile(a)redhat.com>
Date: Sat Mar 22 03:47:58 2014 +0100
Documented how to publish a document using Koji.
en-US/publican.xml | 193 ++++++++++------------------------------------------
1 files changed, 36 insertions(+), 157 deletions(-)
---
diff --git a/en-US/publican.xml b/en-US/publican.xml
index 08fe235..c752590 100644
--- a/en-US/publican.xml
+++ b/en-US/publican.xml
@@ -142,10 +142,8 @@
</table>
</section>
<section id="sect-publican-validating">
- <title>Validating XML Code</title>
- <para>
- <remark>Hic sunt leones.</remark>
- </para>
+ <title>Validating a Document</title>
+ <remark>Hic sunt leones.</remark>
</section>
<section id="sect-publican-building">
<title>Building a Document</title>
@@ -255,179 +253,60 @@
</section>
<section id="sect-publican-publishing">
<title>Publishing a Document</title>
- <para>
- Publishing a document to the Fedora Documentation website isn't that difficult when <application>Publican</application> is doing the heavy lifting. It is assumed that you already have the repository cloned on the computer that <application>Publican</application> will be working from and that your configuration is complete.
- </para>
- <warning>
- <para>
- Documents produced with versions of Publican prior to 2.5 are not compatible with the current website structure. Always make sure that you have the latest version of Publican installed before you publish documents.
- </para>
- </warning>
- <section id="sect-publican-publishing-preparing">
- <title>Preparing Your System</title>
+ <section id="sect-publican-publishing-adding">
+ <title>Adding a New Document</title>
+ <remark>Hic sunt leones...</remark>
+ </section>
+ <section id="sect-publican-publishing-updating">
+ <title>Updating a Document</title>
<para>
- Before we start building your documents into the proper formats for user consumption we need to pull down the webpage source which you'll later add your document into and commit. The following procedure will instruct you on how to do this.
+ To publish your document on the <ulink url="http://docs.fedoraproject.org/">Fedora Documentation</ulink> website, complete the following steps:
</para>
- <itemizedlist>
- <listitem>
+ <procedure id="proc-publican-publishing">
+ <step>
<para>
- Create a local copy of the git repository of the docs.fedoraproject.org website: <command>git clone ssh://USERNAME@git.fedorahosted.org/git/docs/web.git</command> where <literal>USERNAME</literal> is your FAS username.
+ Make sure that the <filename>publican.cfg</filename> file in the main directory of your document contains the following line:
</para>
- <note>
- <para>
- This download will take some time, even on fast connections.
- </para>
- </note>
- </listitem>
- <listitem>
+ <programlisting>os_ver: .el6</programlisting>
+ </step>
+ <step>
<para>
- Change into the directory into which you downloaded the <literal>web.git</literal> repo, and make a copy of <literal>homepage.tmp</literal> named <literal>homepage.cfg</literal>:<command>cp homepage.tmp homepage.cfg</command>
+ Update the <filename><replaceable>language</replaceable>/Revision_History.xml</filename> file to ensure that the document has a unique revision number. To create a new entry in the revision history, use the following command:
</para>
- </listitem>
- <listitem>
+ <screen><command>publican add_revision --lang <replaceable>language</replaceable> \</command>
+ <command>--firstname <replaceable>first_name</replaceable> --surname <replaceable>surname</replaceable> --email <replaceable>email</replaceable> \</command>
+ <command>--member "<replaceable>description</replaceable>"</command></screen>
<para>
- Edit the <literal>homepage.cfg</literal> file to provide the absolute paths to the <literal>fedoradocs.db</literal> file and the <literal>public_html</literal> directory. For example, if you downloaded the <literal>web.git</literal> repo to the <literal>fedoradocs</literal> subdirectory of your home directory, your homepage.cfg file might look like:
+ Replace <replaceable>language</replaceable> with a selected language code, <replaceable>first_name</replaceable> with your given name, <replaceable>surname</replaceable> with your surname, <replaceable>email</replaceable> with your email address, and <replaceable>description</replaceable> with a brief description of your changes.
</para>
- <programlisting>db_file: /home/jsmith/fedoradocs/web/fedoradocs.db
-toc_path: /home/jsmith/fedoradocs/web/public_html
-host: http://docs.fedoraproject.org
-title: "Fedora Documentation"
-search:</programlisting>
- </listitem>
- <listitem>
- <para>
- Make sure you have the latest version of Publican and the Fedora brand package. As root, run: <command>yum update publican publican-fedora</command>
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="sect-publican-publishing-publishing">
- <title>Publishing a Document on the Web</title>
- <warning>
- <para>
- Publican now controls the directory structure and the SQLite database that manages the site and its tables of contents. Do not add or remove directories from the directory tree manually as we did in the past.
- </para>
- </warning>
- <warning>
- <para>
- If you are publishing draft documentation, be sure to follow the instructions described at Publishing draft documentation first.
- </para>
- </warning>
- <warning>
- <para>
- If you are publishing the final version of documentation that was first published in the "Draft Documentation" category, be sure to follow the instructions described at Unpublishing draft documentation first.
- </para>
- </warning>
- <note>
- <title>Incorrect product or version</title>
- <para>If the publish results in an incorrect product or version, check the
- <filename><replaceable>Type</replaceable>_Info.xml</filename> to ensure
- the <literal>productname</literal> and <literal>productversion</literal>
- elements match the desired output. If they are correct, check the
- <filename>publican.cfg</filename> file for lines that begin with
- <literal>version</literal> or <literal>web_version_label</literal>. Delete
- those lines, if they exist.
- </para>
- </note>
- <itemizedlist>
- <listitem>
+ </step>
+ <step>
<para>
- Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run: <command>git pull</command>
+ Package your document as a source RPM (SRPM):
</para>
- </listitem>
- <listitem>
+ <synopsis><command>publican package --lang <replaceable>language</replaceable></command></synopsis>
<para>
- Change to the directory where you keep a checked-out copy of the document that you want to publish, then run: <command>publican build --embedtoc --publish --formats epub,html,html-single,pdf --langs <replaceable>LANGUAGE_CODES</replaceable></command> where <literal>LANGUAGE_CODES</literal> is a comma-separated list of the languages in which you want to publish this document.
+ Replace <replaceable>language</replaceable> with a selected language code. This command stores the newly created SRPM package in the <filename class="directory">tmp/rpm/</filename> directory and prints the absolute path to this file to standard output. If you intend to publish your document in more than one language, repeat this step with a different language code.
</para>
- </listitem>
- <listitem>
+ </step>
+ <step>
<para>
- Browse to the publish subdirectory and to the documents themselves inside it to ensure that the documents have built as you expected. In particular, verify the product name is <literal>Fedora</literal> (note capitalization), the version number is correct, the document title is properly capitalized and spaced: for example, <literal>Foo Guide</literal>, not <literal>foo-guide</literal>
+ Push the SRPM package created in the previous step to Koji:
</para>
- </listitem>
- <listitem>
+ <synopsis><command>koji build el6-docs <replaceable>package_name</replaceable></command></synopsis>
<para>
- Install the book to the Fedora website: <command>publican install_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE</command> where <literal>PATH_TO_SITE_CONFIG_FILE</literal> is the path to the <literal>homepage.cfg</literal> file in your local copy of the docs.fedoraproject.org website, and <literal>LANGUAGE_CODE</literal> is the language in which you are publishing the document. Note that you can only run <command>publican install_book</command> for one language at a time.
+ Replace <replaceable>package_name</replaceable> with a path to the SRPM package.
</para>
- </listitem>
- <listitem>
- <para>
- Change to the directory in which you keep your local copy of the site and run:
- </para>
- <screen><command>git add .</command>
-<command>git commit -m "DESCRIPTION_OF_YOUR_CHANGES"</command>
-<command>git push</command></screen>
- </listitem>
- </itemizedlist>
+ </step>
+ </procedure>
</section>
<section id="sect-publican-publishing-removing">
- <title>Removing a Document from the Web</title>
- <para>
- To remove a document for a particular version of Fedora in a particular language:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run: <command>git pull</command>
- </para>
- </listitem>
- <listitem>
- <para>
- Change to the directory where you keep a checked-out copy of the document that you want to remove, then run: <command>publican remove_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE</command> where <literal>PATH_TO_SITE_CONFIG_FILE</literal> is the path to the <literal>homepage.cfg</literal> file in your local copy of the docs.fedoraproject.org website, and <literal>LANGUAGE_CODE</literal> is the language in which you are removing the document. Note that you can only run <command>publican remove_book</command> for one language at a time.
- </para>
- </listitem>
- <listitem>
- <para>
- Change to the directory in which you keep your local copy of the site and run:
- </para>
- <screen><command>git add .</command>
-<command>git commit -m "DESCRIPTION_OF_YOUR_CHANGES"</command>
-<command>git push</command></screen>
- </listitem>
- <listitem>
- <para>
- Publican can only remove the local files and directories on your system, not their record in Git. To remove the deleted files from your local Git repo, run: <command>for f in $(git ls-files --deleted); do git rm $f; done </command>. Then push these changes to the remote repo: <command>git commit -m "rm unused files" git push</command>
- </para>
- <warning>
- <para>
- A <command>git rm</command> command gone wrong can cause widespread damage to the documentation site. If you are not absolutely sure of what you are doing, ask for help.
- </para>
- </warning>
- </listitem>
- </itemizedlist>
- </section>
- <section id="sect-publican-publishing-updating">
- <title>Updating a Document on the Web</title>
- <para>
- To update a document previously published in a particular language for a particular version of Fedora, change into the directory in which you keep a checked-out copy of the document, then run <command>publican install_book</command>, as if you were installing it for the first time. Publican automatically replaces the old version with the new one.
- </para>
- </section>
- <section id="sect-publican-publishing-draft">
- <title>Marking a Documentation as Draft</title>
- <para>
- Release early, release often.
- </para>
- <para>
- Documents can be released before they are completely ready for the users. When this happens it's important to mark and publish the document as a draft. To do this there are three things that need to be done so that everyone knows that the guide isn't complete and ready for public consumption.
- </para>
- <para>
- The first is setting the draft switch in the document itself. To do this you need to add <command>status="draft"</command> to your <literal>Doc_Name.xml</literal> file in the <literal>book</literal> or <literal>article</literal> heading so it looks like <command>book status="draft"</command>. This provides a draft watermark on all pages of the text.
- </para>
- <para>
- The next task is to modify your <literal>Book_Info.xml</literal> or <literal>Article_Info.xml</literal> file. Change the <literal>productname</literal>tag to Fedora Draft Documentation and remove the contents of <literal>productnumber</literal>. Optionally, if you plan to release the document for a particular Fedora release, include the Fedora release number in the <literal>edition</literal> tag. For example, if you plan to release the book for Fedora 14, you would set edition to: <command>14.0.1</command>. Here 14.0.1 signifies Fedora 14, edition 0.1.
- </para>
- <para>
- Lastly, in the <literal>Publican.cfg</literal> add the following lines: <command>version: 0.1</command> and <command>web_version_label: UNUSED</command>.
- </para>
- <para>
- After completing the above tasks your guide will be sufficiently marked as draft and can safely be published to the Docs website.
- </para>
+ <title>Removing a Document</title>
+ <remark>Hic sunt leones...</remark>
</section>
</section>
<section id="sect-publican-packaging">
- <title>Building RPM Packages</title>
- <para>
- <remark>Hic sunt leones.</remark>
- </para>
+ <title>Packaging a Document</title>
+ <remark>Hic sunt leones.</remark>
</section>
</chapter>
10 years, 2 months
[documentation-guide] Updated the introductory part of the chapter about Publican.
by jhradile
commit 8635294de219bb7844d312ec2676957f3680b7a8
Author: Jaromir Hradilek <jhradile(a)redhat.com>
Date: Sat Mar 22 02:34:59 2014 +0100
Updated the introductory part of the chapter about Publican.
en-US/publican.xml | 7 +++----
1 files changed, 3 insertions(+), 4 deletions(-)
---
diff --git a/en-US/publican.xml b/en-US/publican.xml
index 80f20a0..08fe235 100644
--- a/en-US/publican.xml
+++ b/en-US/publican.xml
@@ -5,15 +5,14 @@
]>
<chapter id="chap-publican">
<title>Publican</title>
- <!-- jhradilek: The following text is not a final; don't worry, I'll fix it. -->
<para>
- <application>Publican</application> is a program that creates the end product that our customers see. The program creates html, html-single, PDF, and ePub formatted files from DocBook XML source code. The files that Publican builds can then be uploaded to a website or packaged in an RPM.
+ <application>Publican</application> is an open-source publishing system for documentation authored in DocBook XML. It can be used to create and build individual articles and books, manage multiple book sets, or to maintain entire documentation websites. In addition, it can also be used to create RPM packages for easy distribution of documentation builds to other machines.
</para>
<para>
- <application>Publican</application> is a command line interface (CLI) program that uses several commands for creating user files from DocBook XML source code. <application>Publican</application> will take care of several tasks for you including building a new book or article, build the book in several formats, and create an RPM package that can be used to install the document locally onto a computer.
+ Publican produces high-quality documents in a number of commonly used file formats such as HTML, PDF, or EPUB. To ensure that all documents produced for a specific project have a consistent look, it uses so called <firstterm>brands</firstterm> to add logos, define color schemes, and set the overall visual style of the output files.
</para>
<para>
- <application>Publican</application> uses modules called <firstterm>brands</firstterm> to add logos and color schemes to documents produced for a specific project, and thus ensures that the look of these documents is consistent. At the top right of every HTML page, the Fedora brand includes a link back to the Fedora documentation site, from a graphic containing the English word "Documentation". We can localise this graphic so that the word "Documentation appears in the same language into which the document itself is translated.
+ The Fedora Documentation Project uses Publican to produce all documents located on the <ulink url="http://docs.fedoraproject.org/">Fedora Documentation</ulink> website.
</para>
<section id="sect-publican-installing">
<title>Installing Publican</title>
10 years, 2 months
[documentation-guide] Updated the copyright date and Bugzilla product name.
by jhradile
commit 0d063c68066fe1096c76d9c055bf111cbe46a6b9
Author: Jaromir Hradilek <jhradile(a)redhat.com>
Date: Tue Mar 18 03:29:04 2014 +0100
Updated the copyright date and Bugzilla product name.
en-US/Documentation_Guide.ent | 4 ++--
1 files changed, 2 insertions(+), 2 deletions(-)
---
diff --git a/en-US/Documentation_Guide.ent b/en-US/Documentation_Guide.ent
index 6018cd3..d6b7b83 100644
--- a/en-US/Documentation_Guide.ent
+++ b/en-US/Documentation_Guide.ent
@@ -1,4 +1,4 @@
-<!ENTITY PRODUCT "Documentation">
+<!ENTITY PRODUCT "Fedora Documentation">
<!ENTITY BOOKID "documentation-guide">
-<!ENTITY YEAR "2011">
+<!ENTITY YEAR "2011–2014">
<!ENTITY HOLDER "Fedora Project Contributors">
10 years, 2 months
[fedora-cookbook] master: chapter skeleton (78d7312)
by Pete Travis
Repository : http://git.fedorahosted.org/cgit/docs/fedora-cookbook.git
On branch : master
>---------------------------------------------------------------
commit 78d731206bcc7be5950748f13f927b9686d0f6b8
Author: Pete Travis <immanetize(a)fedoraproject.org>
Date: Fri Mar 21 23:45:58 2014 -0400
chapter skeleton
>---------------------------------------------------------------
en-US/Cloud.xml | 9 +++++++++
en-US/Communications.xml | 9 +++++++++
en-US/Fedora_Cookbook.xml | 7 +++++++
en-US/Multimedia.xml | 9 +++++++++
en-US/Networking.xml | 9 +++++++++
en-US/Security.xml | 9 +++++++++
en-US/Storage.xml | 9 +++++++++
en-US/Virtualization.xml | 9 +++++++++
8 files changed, 70 insertions(+), 0 deletions(-)
diff --git a/en-US/Cloud.xml b/en-US/Cloud.xml
new file mode 100644
index 0000000..5122196
--- /dev/null
+++ b/en-US/Cloud.xml
@@ -0,0 +1,9 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Fedora_Cookbook.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="Cloud">
+<title>Cloud</title>
+
+<para /> </chapter>
diff --git a/en-US/Communications.xml b/en-US/Communications.xml
new file mode 100644
index 0000000..b6b8f58
--- /dev/null
+++ b/en-US/Communications.xml
@@ -0,0 +1,9 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Fedora_Cookbook.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="Communications">
+<title>Communications</title>
+
+<para /> </chapter>
diff --git a/en-US/Fedora_Cookbook.xml b/en-US/Fedora_Cookbook.xml
index 8a99fcf..989add2 100644
--- a/en-US/Fedora_Cookbook.xml
+++ b/en-US/Fedora_Cookbook.xml
@@ -11,3 +11,10 @@
<index />
</book>
+<xi:include href="Networking.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<xi:include href="Storage.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<xi:include href="Communications.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<xi:include href="Multimedia.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<xi:include href="Cloud.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<xi:include href="Virtualization.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<xi:include href="Security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
diff --git a/en-US/Multimedia.xml b/en-US/Multimedia.xml
new file mode 100644
index 0000000..b7d4727
--- /dev/null
+++ b/en-US/Multimedia.xml
@@ -0,0 +1,9 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Fedora_Cookbook.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="Multimedia">
+<title>Multimedia</title>
+
+<para /> </chapter>
diff --git a/en-US/Networking.xml b/en-US/Networking.xml
new file mode 100644
index 0000000..53e962b
--- /dev/null
+++ b/en-US/Networking.xml
@@ -0,0 +1,9 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Fedora_Cookbook.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="Networking">
+<title>Networking</title>
+
+<para /> </chapter>
diff --git a/en-US/Security.xml b/en-US/Security.xml
new file mode 100644
index 0000000..2f7e38d
--- /dev/null
+++ b/en-US/Security.xml
@@ -0,0 +1,9 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Fedora_Cookbook.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="Security">
+<title>Security</title>
+
+<para /> </chapter>
diff --git a/en-US/Storage.xml b/en-US/Storage.xml
new file mode 100644
index 0000000..5511e0b
--- /dev/null
+++ b/en-US/Storage.xml
@@ -0,0 +1,9 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Fedora_Cookbook.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="Storage">
+<title>Storage</title>
+
+<para /> </chapter>
diff --git a/en-US/Virtualization.xml b/en-US/Virtualization.xml
new file mode 100644
index 0000000..9078353
--- /dev/null
+++ b/en-US/Virtualization.xml
@@ -0,0 +1,9 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Fedora_Cookbook.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="Virtualization">
+<title>Virtualization</title>
+
+<para /> </chapter>
10 years, 2 months
[fedora-cookbook] master: minor corrections, bumping revhistory (554e3bd)
by Pete Travis
Repository : http://git.fedorahosted.org/cgit/docs/fedora-cookbook.git
On branch : master
>---------------------------------------------------------------
commit 554e3bd7b9814aaf5ebc85196edebd5bacb51db0
Author: Pete Travis <immanetize(a)fedoraproject.org>
Date: Fri Mar 21 20:53:01 2014 -0400
minor corrections, bumping revhistory
>---------------------------------------------------------------
en-US/Author_Group.xml | 9 ++++-----
en-US/Book_Info.xml | 6 +++---
en-US/Documenting_Fedora/writing_recipes.xml | 2 +-
en-US/Revision_History.xml | 17 ++++++++---------
4 files changed, 16 insertions(+), 18 deletions(-)
diff --git a/en-US/Author_Group.xml b/en-US/Author_Group.xml
index 3b0d59e..5329903 100644
--- a/en-US/Author_Group.xml
+++ b/en-US/Author_Group.xml
@@ -5,13 +5,12 @@
]>
<authorgroup>
<author>
- <firstname>Enter your first name here.</firstname>
- <surname>Enter your surname here.</surname>
+ <firstname>Pete</firstname>
+ <surname>Travis</surname>
<affiliation>
- <orgname>Enter your organisation's name here.</orgname>
- <orgdiv>Enter your organisational division here.</orgdiv>
+ <orgname>Fedora Project</orgname>
</affiliation>
- <email>Enter your email address here.</email>
+ <email>immanetize AT fedoraproject.org</email>
</author>
</authorgroup>
diff --git a/en-US/Book_Info.xml b/en-US/Book_Info.xml
index 5e5f8fa..474f102 100644
--- a/en-US/Book_Info.xml
+++ b/en-US/Book_Info.xml
@@ -5,14 +5,14 @@
]>
<bookinfo id="book-Documentation-Fedora_Cookbook-Fedora_Cookbook">
<title>Fedora Cookbook</title>
- <subtitle>Enter a short description here.</subtitle>
+ <subtitle>A collection of tutorials for Fedora</subtitle>
<productname>Documentation</productname>
<productnumber>0.1</productnumber>
<edition>0</edition>
<pubsnumber>0</pubsnumber>
<abstract>
- <para>
- A short overview and summary of the book's subject and purpose, traditionally no more than one paragraph long. Note: the abstract will appear in the front matter of your book and will also be placed in the description field of the book's RPM spec file.
+ <para>
+ The Fedora Cookbook contains a collection of tutorials and short guides. The book is designed to encourage community participation; submissions are welcome and the Fedora Docs community provides review and pubishing. If you would like an addition to this guide, you can request or get help to write it.
</para>
</abstract>
<corpauthor>
diff --git a/en-US/Documenting_Fedora/writing_recipes.xml b/en-US/Documenting_Fedora/writing_recipes.xml
index d7fa2e6..e6653d2 100644
--- a/en-US/Documenting_Fedora/writing_recipes.xml
+++ b/en-US/Documenting_Fedora/writing_recipes.xml
@@ -59,7 +59,7 @@
</para></step>
<step>
<para>
- Download a template from <ulink url="https://git.fedorahosted.org/cgit/docs/fedora-cookbook.git/tree/en-US/exa...">the repository</ulink> maintained by the Fedora Docs team. Choose the format you like, then click <guilabel>plain<guilabel> to get it in a format you can cut and paste into an editor.
+ Download a template from <ulink url="https://git.fedorahosted.org/cgit/docs/fedora-cookbook.git/tree/en-US/exa...">the repository</ulink> maintained by the Fedora Docs team. Choose the format you like, then click <guilabel>plain</guilabel> to get it in a format you can cut and paste into an editor.
</para>
<itemizedlist>
<listitem>
diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml
index cea54f3..66a49bf 100644
--- a/en-US/Revision_History.xml
+++ b/en-US/Revision_History.xml
@@ -1,27 +1,26 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Fedora_Cookbook.ent">
-%BOOK_ENTITIES;
]>
<appendix id="appe-Documentation-Fedora_Cookbook-Revision_History">
<title>Revision History</title>
- <simpara>
+ <simpara>
<revhistory>
<revision>
- <revnumber>0.0-0</revnumber>
- <date>Fri Mar 21 2014</date>
+ <revnumber>0.0-1</revnumber>
+ <date>Sat Mar 22 2014</date>
<author>
- <firstname>Enter your first name here.</firstname>
- <surname>Enter your surname here.</surname>
- <email>Enter your email address here.</email>
+ <firstname>Pete</firstname>
+ <surname>Travis</surname>
+ <email>immanetize AT fedoraproject.org</email>
</author>
<revdescription>
<simplelist>
- <member>Initial creation by publican</member>
+ <member>member</member>
</simplelist>
</revdescription>
</revision>
</revhistory>
+
</simpara>
</appendix>
10 years, 2 months