Diferencias

Muestra las diferencias entre dos versiones de la página.

@@ Línea 1: / Línea 1: @@
+====== Asciidoc ======
+===== Introduction =====
+Keeping notes is an integral part of using any Linux distribution. Keeping them in plain text allows one to use them from a console during initial setup; using a consistent markup for plain text adds to the readability of the notes.
+//asciidoc// is one of the tools that provide such a consistent markup. Source highlighting, for those who prefer it, can add to the readability of the text file.
+//asciidoc// can produce HTML files, an added bonus as it allows to interlink notes and makes browsing them with //lynx// more effective. It can also work in tandem with [[howtos:software:man2html_mini_howto|man2html]] to provide HTML access to all installed //man// pages on the fly.
+For an interesting read about //asciidoc// see [[https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272|Living the Future of Technical Writing]].
+===== Helper Packages and Files =====
+==== Asciidoctor ====
+Consider installing [[http://asciidoctor.org/|Asciidoctor]].
+==== Dblatex ====
+To convert //asciidoc// files to PDF, install
+[[http://slackbuilds.org/graphics/dblatex/|dblatex]] from SlackBuilds.org. See
+[[http://dblatex.sourceforge.net/|documentation]], [[#PDF]].
+==== Source-highlight ====
+To highlight source listings, install
+[[http://slackbuilds.org/system/source-highlight/|source-highlight]] from SlackBuilds.org. See [[https://www.gnu.org/software/src-highlite/source-highlight.html|online manual]].
+This:
+<code>
+[source,bash]
+---------------------------------------------------------------------------
+#!/bin/bash
+export LANG=en_US.UTF-8
+---------------------------------------------------------------------------
+</code>
+renders as (this is DokuWiki's GeSHi highlighting, but gives the general idea):
+<code bash>
+#!/bin/bash
+export LANG=en_US.UTF-8
+</code>
+==== Vim Syntax Highlighter ====
+If //asciidoc.vim// is not available locally, [[https://asciidoc.googlecode.com/hg/vim/syntax/asciidoc.vim|download]]. Otherwise:
+**''$ mkdir -p $HOME/.vim/syntax''**
+**''$ cp /usr/share/vim/vimVERSION/syntax/asciidoc.vim $HOME/.vim/syntax/''**
+and see [[http://www.methods.co.nz/asciidoc/chunked/ape.html|Appendix E. Vim Syntax Highlighter]].
+Highlighting can also work by inserting at the bottom of the file:
+<code>// vim: set syntax=asciidoc:</code>
+===== User Guide =====
+The user guide file is found in ///usr/doc/asciidoc-VERSION/doc/asciidoc.txt//. To make the //AsciiDoc User Guide//:
+**''$ asciidoc -b xhtml11 -a icons -a iconsdir=/etc/asciidoc/images/icons FILENAME''**
+and see ///usr/doc/asciidoc-VERSION/doc/asciidoc.html//. For more see [[http://asciidoc.org/|asciidoc.org]].
+===== Source Files =====
+==== TXT ====
+It is a //convention// for //asciidoc// files to have a //.txt// extension.
+==== Common Variables ====
+To organize the use of common variables in all files, make a directory //include//. Common paths, for example, can be put in a //paths.txt// as a series of:
+<file>
+:pathname: {pathname=/path/to/somewhere}
+</file>
+Then, at the header of each file put:
+<file>
+include::/path/to/include/paths.txt[]
+</file>
+and in text use as:
+<file>
+{pathname}/remaining/path
+</file>
+==== System Attributes ====
+Any variable that can be defined in //bash// with
+**''NAME="$(commands)"''**
+can also be defined in //asciidoc// as a [[http://asciidoc.org/userguide.html#X24|system attribute]]. First define the attribute in the header section:
+<file>
+:NAME: {sys:commands}
+</file>
+then use in text as:
+<file>
+{NAME}
+</file>
+==== Man ====
+Linking to //man// pages in HTML is very useful. See [[howtos:software:man2html_mini_howto|man2html Mini HOWTO]] on how to set the infrastructure. To see grep(1) use
+<file>
+http://localhost/cgi-bin/man/man2html?1+grep[grep(1)]
+</file>
+===== Output =====
+==== XHTML ====
+To make an HTML file:
+**''$ asciidoc -b xhtml11 FILENAME''**
+To use icons, mainly for admonition paragraphs, add the options:
+**''-a icons -a iconsdir=/etc/asciidoc/images/icons''**
+To have a fixed-width HTML, add:
+**''-a max-width=45em''**
+To use additional custom CSS, add:
+**''-a stylesheet=/path/to/stylesheet.css''**
+It may be helpful to put an alias in //.bashrc//:
+<code bash>
+alias ad="/usr/bin/asciidoc.py \
+  -b xhtml11 \
+  -a icons -a max-width=45em \
+  -a iconsdir=/etc/asciidoc/images/icons \
+  -a stylesdir=/etc/asciidoc/stylesheets \
+  -a stylesheet=/path/to/stylesheet.css"
+</code>
+==== PDF ====
+To make a PDF file, first install [[#dblatex]]. Then:
+**''$ asciidoc -b docbook45 FILENAME''**
+**''$ dblatex FILENAME.xml''**
+==== DokuWiki ====
+The //asciidoc// files can be converted to //DokuWiki// format for the Slackware Documentation Project. There are various ways to do this, and one of the more straightforward ones is to convert the HTML files produced by //asciidoc// using the //perl// module [[http://search.cpan.org/~diberri/HTML-WikiConverter-DokuWiki-0.53/lib/HTML/WikiConverter/DokuWiki.pm|HTML::WikiConverter::DokuWiki]], see also [[http://search.cpan.org/dist/HTML-WikiConverter/lib/HTML/WikiConverter.pm|HTML::WikiConverter]].
+**''# cpan''**
+''cpan[1]>'' **''install HTML::WikiConverter::DokuWiki''**
+**''$ html2wiki --dialect DokuWiki input.html > output.wiki''**
+====== Sources ======
+  * Original source: [[http://www.linuxquestions.org/questions/slackware-14/asciidoc-mini-howto-4175528145/|asciidoc mini howto]]
+  * Originally written by [[wiki:user:pdi | pdi]]
+  * Contributions by [[wiki:user:markand | markand]]
+{{tag>howtos asciidoc}}

Traza:

Diferencias

Navegación

Búsqueda

Herramientas

En otros idiomas

SlackDocs

Slackware Links

QR Code