[docs-beginner] master: Introduction to the why of docbook (2a4601d)

[jsmith at fedoraproject.org]

Repository : http://git.fedorahosted.org/cgit/docs-beginner.git

On branch  : master

>---------------------------------------------------------------

commit 2a4601dafd55c724c103106ad52d58a66e64f65e
Author: Jared K. Smith <jaredsmith at jaredsmith.net>
Date:   Thu Aug 7 10:34:44 2014 -0400

    Introduction to the why of docbook


>---------------------------------------------------------------

 en-US/why_docbook.xml |   65 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 65 insertions(+), 0 deletions(-)

diff --git a/en-US/why_docbook.xml b/en-US/why_docbook.xml
new file mode 100644
index 0000000..0815625
--- /dev/null
+++ b/en-US/why_docbook.xml
@@ -0,0 +1,65 @@
+<?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 "Documentation_Guide.ent">
+%BOOK_ENTITIES;
+]>
+
+<chapter id="chap-why-docbook">
+      <title>Why DocBook?</title>
+      <para>
+              DocBook has many features which make it suitable for
+              documentation in Fedora and other projects.
+      </para>
+      <section>
+              <title>DocBook as an XML Markup Language</title>
+              <para>
+                      DocBook is an implementation of 
+                      <firstterm>Extensible Markup Language (XML)
+                      </firstterm>. XML gives DocBook powerful
+                      flexibility.
+              </para>
+      </section>
+      <section>
+              <title>Human-readable Tags</title>
+              <para>
+                      DocBook tags are generally self-explaining.
+                      They are named after what they define, even 
+                      though shorter terms might make more effiecient
+                      use of space. This makes it easy for writers
+                      and editors to quickly look at a document and
+                      understand how it is constructed.
+              </para>
+      </section>
+      <section>
+              <title>Text-based Format for Easy Revision Control</title>
+              <para>
+                      Version control provides two critical features
+                      for collaborative documentation work:
+                      concurrent editing and history. The text-based
+                      format of DocBook makes it well-suited to 
+                      being managed by a version control system.
+              </para>
+      </section>
+      <section>
+              <title>Separation Between Content and Style</title>
+              <para>
+                      The DocBook standard separates a document's
+                      content and its formatting. The writer uses XML
+                      tags to structure the elements of document, and
+                      the formatting can be changed independently
+                      later. A change to the formatting of an element
+                      does not require changing every instance of that
+                      element.
+              </para>
+      </section>
+      <section>
+              <title>Output in a Variety of Formats</title>
+              <para>
+                      DocBook is a source format. The
+                      <command>publican</command> tool is used to
+                      generate rendered documents in several different
+                      formats. publican can generate HTML, PDF, and
+                      epub formats from the same source file.
+              </para>
+      </section>
+</chapter>