source: general/genutils/asciidoc.xml@ eebcdb57

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY asciidoc-download-http "https://github.com/asciidoc/asciidoc-py3/releases/download/&asciidoc-version;/asciidoc-&asciidoc-version;.tar.gz">
  <!ENTITY asciidoc-download-ftp  " ">
  <!ENTITY asciidoc-md5sum        "63621686c5235984ce03228563a6383b">
  <!ENTITY asciidoc-size          "1.2 MB">
  <!ENTITY asciidoc-buildsize     "6.3 MB">
  <!ENTITY asciidoc-time          "less than 0.1 SBU">
]>

<sect1 id="asciidoc" xreflabel="asciidoc-&asciidoc-version;">
  <?dbhtml filename="asciidoc.html"?>

  <sect1info>
    <date>$Date$</date>
  </sect1info>

  <title>Asciidoc-&asciidoc-version;</title>

  <indexterm zone="asciidoc">
    <primary sortas="a-asciidoc">asciidoc</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Asciidoc</title>

    <para>
      The <application>Asciidoc</application> package is a text document
      format for writing notes, documentation, articles, books, ebooks,
      slideshows, web pages, man pages and blogs. AsciiDoc files can be
      translated to many formats including HTML, PDF, EPUB, and man page.
    </para>

    &lfs110a_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&asciidoc-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&asciidoc-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &asciidoc-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &asciidoc-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &asciidoc-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &asciidoc-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Asciidoc Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional (tests and runtime)</bridgehead>
    <para role="optional">
      <xref linkend="docbook-xsl"/>,
      <xref linkend="fop"/>,
      <xref linkend="libxslt"/>,
      <xref linkend="lynx"/>,
      <ulink url="https://sourceforge.net/projects/dblatex/">dblatex</ulink>, and
      <ulink url="&w3m-url;">W3m</ulink>
    </para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/asciidoc"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Asciidoc</title>

    <para>
      First, fix a build problem if the optional dependencies are not installed:
    </para>

<screen><userinput remap='pre'>sed -i 's:doc/testasciidoc.1::' Makefile.in &amp;&amp;
rm doc/testasciidoc.1.txt</userinput></screen>

    <para>
      Install <application>Asciidoc</application> by running
      the following commands:
    </para>

<screen><userinput>./configure --prefix=/usr     \
            --sysconfdir=/etc \
            --docdir=/usr/share/doc/asciidoc-&asciidoc-version; &amp;&amp;
make</userinput></screen>

    <para>
      <!--To test the results, issue: <command>make test</command>-->
      This package does not come with a test suite.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install &amp;&amp;
make docs</userinput></screen>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          a2x (symlink to a2x.py),
          a2x.py,
          asciidoc (symlink to asciidoc.py), and
          asciidoc.py
        </seg>
        <seg>None</seg>
        <seg>/etc/asciidoc and
             /usr/share/doc/asciidoc-&asciidoc-version;
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="a2x">
        <term><command>a2x</command></term>
        <listitem>
          <para>
            is a toolchain manager for AsciiDoc
            (converts Asciidoc text files to other file formats)
          </para>
          <indexterm zone="asciidoc a2x">
            <primary sortas="b-a2x">a2x</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="asciidoc-prog">
        <term><command>asciidoc</command></term>
        <listitem>
          <para>
            converts an AsciiDoc text file to HTML or DocBook
          </para>
          <indexterm zone="asciidoc asciidoc-prog">
            <primary sortas="b-asciidoc-prog">asciidoc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>