Panduan Lengkap untuk Menggunakan AsciiDoc di Linux

Brief:Panduan terperinci ini membahas keuntungan menggunakan AsciiDoc dan menunjukkan cara menginstal dan menggunakan AsciiDoc di Linux.

Selama bertahun-tahun saya menggunakan banyak alat yang berbeda untuk menulis artikel, laporan, atau dokumentasi. Saya pikir semuanya dimulai untuk saya dengan Epistol Luc Barthelet di Apple IIc dari editor Prancis Version Soft. Kemudian saya beralih ke alat GUI dengan Microsoft Word 5 yang sangat baik untuk Apple Macintosh, kemudian StarOffice (bagi saya) yang kurang meyakinkan di Sparc Solaris, yang sudah dikenal sebagai OpenOffice ketika saya secara definitif beralih ke Linux. Semua alat ini benar-benar pengolah kata.

Tapi saya tidak pernah benar-benar yakin dengan editor WYSIWYG. Jadi saya menyelidiki banyak format teks yang kurang lebih dapat dibaca manusia:troff, HTML, RTF, TeX/LaTeX, XML dan akhirnya AsciiDoc yang merupakan alat yang paling sering saya gunakan saat ini. Bahkan, saya menggunakannya sekarang untuk menulis artikel ini!

Jika saya membuat sejarah itu, itu karena entah bagaimana loop ditutup. Epistole adalah pengolah kata di era konsol teks. Sejauh yang saya ingat, ada menu dan Anda dapat menggunakan mouse untuk memilih teks — tetapi sebagian besar pemformatan dilakukan dengan menambahkan tag yang tidak mengganggu ke dalam teks. Sama seperti yang dilakukan dengan AsciiDoc. Tentu saja, itu bukan perangkat lunak pertama yang melakukan itu. Tapi itu yang pertama saya gunakan!

Mengapa AsciiDoc (atau format file teks lainnya)?

Saya melihat dua keuntungan dalam menggunakan format teks untuk menulis:pertama, ada pemisahan yang jelas antara konten dan presentasi. Argumen ini terbuka untuk didiskusikan karena beberapa format teks seperti TeX atau HTML memerlukan disiplin yang baik untuk mematuhi pemisahan itu. Dan di sisi lain, Anda entah bagaimana dapat mencapai beberapa tingkat pemisahan dengan menggunakan template dan stylesheet dengan editor WYSIWYG. Saya setuju dengan itu. Tapi saya masih menemukan masalah presentasi mengganggu dengan alat GUI. Padahal, saat menggunakan format teks, Anda dapat fokus pada konten saja tanpa gaya font atau garis janda yang mengganggu Anda dalam tulisan Anda. Tapi mungkin hanya aku? Namun, saya tidak dapat menghitung berapa kali saya menghentikan tulisan saya hanya untuk memperbaiki beberapa masalah gaya kecil — dan kehilangan inspirasi ketika saya kembali ke teks. Jika Anda tidak setuju atau memiliki pengalaman yang berbeda, jangan ragu untuk membantah saya menggunakan bagian komentar di bawah!

Bagaimanapun, argumen kedua saya akan kurang tunduk pada interpretasi pribadi:dokumen berdasarkan format teks sangat dapat dioperasikan . Anda tidak hanya dapat mengeditnya dengan editor teks apa pun pada platform apa pun, tetapi Anda dapat dengan mudah mengelola revisi teks dengan alat seperti git atau SVN, atau mengotomatiskan modifikasi teks menggunakan alat umum seperti sed, AWK, Perl, dan sebagainya. Untuk memberi Anda contoh nyata, saat menggunakan format berbasis teks seperti AsciiDoc, saya hanya perlu satu perintah untuk menghasilkan surat yang sangat dipersonalisasi dari dokumen master, sedangkan pekerjaan yang sama menggunakan editor WYSIWYG akan membutuhkan penggunaan "bidang" yang cerdas. dan melalui beberapa layar wizard.

Apa itu AsciiDoc?

Sebenarnya, AsciiDoc adalah format file. Ini mendefinisikan konstruksi sintaksis yang akan membantu prosesor untuk memahami semantik dari berbagai bagian teks Anda. Biasanya untuk menghasilkan keluaran yang diformat dengan baik.

Meskipun definisi tersebut tampak abstrak, ini adalah sesuatu yang sederhana:beberapa kata kunci atau karakter dalam dokumen Anda memiliki arti khusus yang akan mengubah tampilan dokumen. Ini adalah konsep yang sama persis dengan tag dalam HTML. Namun perbedaan utama dengan AsciiDoc adalah properti dokumen sumber tetap dengan mudah dapat dibaca manusia.

Periksa repositori GitHub kami untuk membandingkan bagaimana output yang sama dapat dihasilkan menggunakan beberapa format file teks umum:(ide halaman manual kopi milik http://www.linuxjournal.com/article/1158)

• coffee.man menggunakan troff yang terhormat prosesor (berdasarkan program RUNOFF 1964). Ini sebagian besar digunakan hari ini untuk menulis halaman manual. Anda bisa mencobanya setelah mendownload coffee.* file dengan mengetikkan man ./coffee.man di prompt perintah Anda.
• coffee.tex menggunakan LaTeX sintaks (1985) untuk mencapai sebagian besar hasil yang sama tetapi untuk output PDF. LaTeX adalah program penyusunan huruf yang sangat cocok untuk publikasi ilmiah karena kemampuannya untuk memformat rumus dan tabel matematika dengan baik. Anda dapat menghasilkan PDF dari sumber LaTeX menggunakan pdflatex coffee.tex
• coffee.html menggunakan format HTML (1991) untuk mendeskripsikan halaman. Anda dapat langsung membuka file tersebut dengan browser web favorit Anda untuk melihat hasilnya.
• coffee.adoc , akhirnya, menggunakan sintaks AsciiDoc (2002). Anda dapat menghasilkan HTML dan PDF dari file tersebut:

asciidoc coffee.adoc                   # HTML output
a2x --format pdf ./coffee.adoc         # PDF output (dblatex)
a2x --fop --format pdf ./coffee.adoc   # PDF output (Apache FOP)

Sekarang Anda telah melihat hasilnya, buka keempat file tersebut menggunakan editor teks favorit Anda (nano, vim, SublimeText, gedit, Atom, ... ) dan bandingkan sumbernya:kemungkinan besar Anda akan setuju bahwa sumber AsciiDoc lebih mudah dibaca — dan mungkin untuk menulis juga.

Bagaimana cara menginstal AsciiDoc di Linux?

AsciiDoc relatif rumit untuk diinstal karena banyaknya dependensi. Maksud saya rumit jika Anda ingin menginstalnya dari sumber. Bagi kebanyakan dari kita, menggunakan pengelola paket mungkin merupakan cara terbaik:

apt-get install asciidoc fop

atau perintah berikut:

yum install acsiidoc fop

(fop hanya diperlukan jika Anda memerlukan backend Apache FOP untuk pembuatan PDF — ini adalah backend PDF yang saya gunakan sendiri)

Rincian lebih lanjut tentang instalasi dapat ditemukan di situs web resmi AsciiDoc. Untuk saat ini, yang Anda butuhkan sekarang adalah sedikit kesabaran, karena, setidaknya pada sistem minimal Debian saya, menginstal AsciiDoc memerlukan 360MB untuk diunduh (kebanyakan karena ketergantungan LaTeX). Yang, bergantung pada bandwidth Internet Anda, dapat memberi Anda banyak waktu untuk membaca sisa artikel ini.

Tutorial AsciiDoc:Bagaimana cara menulis di AsciiDoc?

Saya mengatakannya beberapa kali, AsciiDoc adalah format file teks yang dapat dibaca manusia . Jadi, Anda dapat menulis dokumen Anda menggunakan editor teks pilihan Anda. Bahkan ada editor teks khusus. Tetapi saya tidak akan membicarakannya di sini— hanya karena saya tidak menggunakannya. Namun jika Anda menggunakan salah satunya, jangan ragu untuk membagikan masukan Anda melalui kolom komentar di akhir artikel ini.

Saya tidak bermaksud untuk membuat tutorial sintaks AsciiDoc lagi di sini:sudah banyak tersedia di web. Jadi saya hanya akan menyebutkan konstruksi sintaksis paling dasar yang akan Anda gunakan di hampir semua dokumen. Dari contoh perintah “kopi” sederhana yang dikutip di atas, Anda mungkin melihat:

• judul di AsciiDoc diidentifikasi dengan mendasarinya dengan === atau --- (tergantung pada tingkat judul),
• tebal rentang karakter ditulis di antara awal,
• dan miring antara garis bawah.

Itu adalah konvensi yang cukup umum yang mungkin berasal dari era email pra-HTML. Selain itu, Anda mungkin memerlukan dua konstruksi umum lainnya, yang tidak diilustrasikan dalam contoh saya sebelumnya:hyperlink dan gambar inklusi, yang sintaksnya cukup jelas.

// HyperText links
link:http://dashing-kazoo.flywheelsites.com[ItsFOSS Linux Blog]

// Inline Images
image:https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

// Block Images
image::https://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo]

Tetapi sintaks AsciiDoc jauh lebih kaya dari itu. Jika Anda menginginkan lebih, saya dapat mengarahkan Anda ke lembar contekan AsciiDoc yang bagus:http://powerman.name/doc/asciidoc

Bagaimana cara membuat hasil akhir?

Saya akan menganggap di sini Anda telah menulis beberapa teks mengikuti format AsciiDoc. Jika tidak, Anda dapat mengunduh di sini beberapa file contoh yang disalin langsung dari dokumentasi AsciiDoc:

# Download the AsciiDoc User Guide source document
BASE='https://raw.githubusercontent.com/itsfoss/asciidoc-intro/master'
wget "${BASE}"/{asciidoc.txt,customers.csv}

Karena AsciiDoc dapat dibaca manusia , Anda dapat mengirim teks sumber AsciiDoc langsung ke seseorang melalui email, dan penerima akan dapat membaca pesan itu tanpa basa-basi lagi. Namun, Anda mungkin ingin memberikan beberapa keluaran yang diformat dengan lebih baik. Misalnya sebagai HTML untuk publikasi web (seperti yang saya lakukan untuk artikel ini). Atau sebagai PDF untuk penggunaan cetak atau tampilan.

Dalam semua kasus, Anda memerlukan prosesor . Bahkan, di bawah tenda, Anda akan membutuhkan beberapa prosesor. Karena dokumen AsciiDoc Anda akan diubah menjadi berbagai format perantara sebelum menghasilkan keluaran akhir. Karena beberapa alat digunakan, keluaran dari salah satu alat menjadi masukan alat berikutnya, terkadang kita berbicara tentang rantai alat .

Bahkan jika saya menjelaskan beberapa detail kerja batin di sini, Anda harus memahami sebagian besar dari itu akan disembunyikan dari Anda. Kecuali mungkin saat Anda awalnya harus menginstal alat— atau jika Anda ingin menyempurnakan beberapa langkah proses.

Dalam praktik?

Untuk output HTML, Anda hanya memerlukan asciidoc alat. Untuk rantai alat yang lebih rumit, saya mendorong Anda untuk menggunakan a2x alat (bagian dari distribusi AsciiDoc) yang akan memicu prosesor yang diperlukan agar:

# All examples are based on the AsciiDoc User Guide source document

# HTML output
asciidoc asciidoc.txt
firefox asciidoc.html

# XHTML output
a2x --format=xhtml asciidoc.txt

# PDF output (LaTeX processor)
a2x --format=pdf asciidoc.txt

# PDF output (FOP processor)
a2x --fop --format=pdf asciidoc.txt

Meskipun dapat langsung menghasilkan output HTML, fungsi inti asciidoc alat tetap untuk mengubah dokumen AsciiDoc ke format DocBook perantara. DocBook adalah format berbasis XML yang biasa digunakan untuk (namun tidak terbatas pada) penerbitan dokumentasi teknis. DocBook adalah format semantik. Itu berarti menggambarkan konten dokumen Anda. Tapi tidak presentasinya. Jadi pemformatan akan menjadi langkah transformasi selanjutnya. Untuk itu, apa pun format outputnya, dokumen perantara DocBook diproses melalui prosesor XSLT untuk menghasilkan output secara langsung (misalnya XHTML), atau format perantara lainnya.

Ini adalah kasus ketika Anda membuat dokumen PDF di mana dokumen DocBook akan (sesuai keinginan Anda) dikonversi baik sebagai representasi perantara LaTeX atau sebagai XSL-FO (bahasa berbasis XML untuk deskripsi halaman). Terakhir, alat khusus akan mengonversi representasi tersebut ke PDF.

Langkah-langkah ekstra untuk generasi PDF terutama dibenarkan oleh fakta bahwa toolchain harus menangani pagination untuk output PDF. Sesuatu yang tidak diperlukan untuk format "aliran" seperti HTML.

dblatex atau fop?

Karena ada dua backend PDF, pertanyaan yang biasa muncul adalah “Mana yang terbaik?” Sesuatu yang tidak bisa saya jawab untuk Anda.

Kedua prosesor memiliki pro dan kontra. Dan pada akhirnya, pilihannya adalah kompromi antara kebutuhan dan selera Anda. Jadi saya mendorong Anda untuk meluangkan waktu untuk mencoba keduanya sebelum memilih backend yang akan Anda gunakan. Jika Anda mengikuti jalur LaTeX, dblatex akan menjadi backend yang digunakan untuk menghasilkan PDF. Sedangkan Apache FOP jika Anda lebih suka menggunakan format perantara XSL-FO. Jadi jangan lupa untuk melihat dokumentasi alat-alat ini untuk melihat betapa mudahnya menyesuaikan output dengan kebutuhan Anda. Kecuali tentu saja jika Anda puas dengan output default!

Bagaimana cara menyesuaikan keluaran AsciiDoc?

AsciiDoc ke HTML

Di luar kotak, AsciiDoc menghasilkan dokumen yang cukup bagus. Tapi cepat atau lambat Anda akan menyesuaikan penampilan mereka.

Perubahan yang tepat akan tergantung pada backend yang Anda gunakan. Untuk output HTML, sebagian besar perubahan dapat dilakukan dengan mengubah stylesheet CSS yang terkait dengan dokumen.

Sebagai contoh, katakanlah saya ingin menampilkan semua judul bagian dengan warna merah, saya dapat membuat custom.css berikut berkas:

h2 {
    color: red;
}

Dan proses dokumen menggunakan perintah yang sedikit dimodifikasi:

# Set the 'stylesheet' attribute to
# the absolute path to our custom CSS file
asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt

Anda juga dapat membuat perubahan pada tingkat yang lebih baik dengan melampirkan peran atribut ke sebuah elemen. Ini akan diterjemahkan menjadi kelas atribut dalam HTML yang dihasilkan.

Misalnya, coba ubah dokumen pengujian kami untuk menambahkan atribut role ke paragraf pertama teks:

[role="summary"]
AsciiDoc is a text document format ....

Kemudian tambahkan aturan berikut ke custom.css berkas:

.summary {
    font-style: italic;
}

Buat ulang dokumen:

asciidoc -a stylesheet=$PWD/custom.css asciidoc.txt

1. et voila:paragraf pertama sekarang ditampilkan dalam huruf miring. Dengan sedikit kreativitas, kesabaran, dan beberapa tutorial CSS, Anda akan dapat menyesuaikan dokumen sesuai keinginan.

AsciiDoc ke PDF

Menyesuaikan output PDF agak lebih kompleks. Bukan dari sudut pandang penulis karena teks sumber akan tetap identik. Akhirnya menggunakan atribut peran yang sama seperti di atas untuk mengidentifikasi bagian-bagian yang memerlukan perawatan khusus.

Tetapi Anda tidak dapat lagi menggunakan CSS untuk menentukan pemformatan untuk keluaran PDF. Untuk pengaturan yang paling umum, ada parameter yang dapat Anda atur dari baris perintah. Beberapa parameter dapat digunakan baik dengan dblatex dan fop backend, yang lain khusus untuk setiap backend.

Untuk daftar parameter yang didukung dblatex, lihat http://dblatex.sourceforge.net/doc/manual/sec-params.html

Untuk daftar parameter DocBook XSL, lihat http://docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html

Karena penyesuaian margin adalah persyaratan yang cukup umum, Anda mungkin juga ingin melihatnya:http://docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

Jika nama parameter agak konsisten antara dua backend, argumen baris perintah yang digunakan untuk meneruskan nilai tersebut ke backend berbeda antara dblatex dan memukul . Jadi, periksa dulu sintaks Anda jika ternyata, ini tidak berfungsi. Tapi jujur, saat menulis artikel ini saya tidak bisa membuat body.font.family parameter bekerja dengan dblatex bagian belakang. Karena saya biasanya menggunakan fop , mungkin aku melewatkan sesuatu? Jika Anda memiliki lebih banyak petunjuk tentang itu, saya akan dengan senang hati membaca saran Anda di bagian komentar di akhir artikel ini!

Layak disebutkan menggunakan font non-standar— bahkan dengan fop -memerlukan beberapa pekerjaan ekstra. Tapi itu didokumentasikan dengan cukup baik di situs web Apache:https://xmlgraphics.Apache.org/fop/trunk/fonts.html#bulk

# XSL-FO/FOP
a2x -v --format pdf \
    --fop \
    --xsltproc-opts='--stringparam page.margin.inner 10cm' \
    --xsltproc-opts='--stringparam body.font.family Helvetica' \
    --xsltproc-opts='--stringparam body.font.size 8pt' \
    asciidoc.txt

# dblatex
# (body.font.family _should_ work, but, apparently, it isn't ?!?)
a2x -v --format pdf \
    --dblatex-opts='--param page.margin.inner=10cm' \
    --dblatex-opts='--stringparam body.font.family Helvetica' \
    asciidoc.txt

Setelan terperinci untuk pembuatan PDF

Parameter global bagus jika Anda hanya perlu menyesuaikan beberapa pengaturan yang telah ditentukan sebelumnya. Tetapi jika Anda ingin menyempurnakan dokumen (atau mengubah tata letak sepenuhnya), Anda memerlukan upaya ekstra.

Inti dari pemrosesan DocBook adalah XSLT. XSLT adalah bahasa komputer, dinyatakan dalam notasi XML, yang memungkinkan untuk menulis transformasi sewenang-wenang dari dokumen XML ke ... sesuatu yang lain. XML atau tidak.

Misalnya, Anda perlu memperluas atau memodifikasi lembar gaya DocBook XSL untuk menghasilkan kode XSL-FO untuk gaya baru yang mungkin Anda inginkan. Dan jika Anda menggunakan dblatex backend, ini mungkin memerlukan modifikasi stylesheet DocBook-to-LaTeX XSLT yang sesuai. Dalam kasus terakhir itu, Anda mungkin juga perlu menggunakan paket LaTeX khusus. Tapi saya tidak akan fokus pada itu karena dblatex bukan backend yang saya gunakan sendiri. Saya hanya dapat mengarahkan Anda ke dokumentasi resmi jika Anda ingin tahu lebih banyak. Tapi sekali lagi, jika Anda sudah familiar dengan itu, silakan bagikan tips dan trik Anda di bagian komentar!

Bahkan saat hanya fokus pada fop , Saya tidak benar-benar memiliki ruang di sini untuk merinci seluruh prosedur. Jadi, saya hanya akan menunjukkan kepada Anda perubahan yang dapat Anda gunakan untuk mendapatkan hasil yang sama seperti yang diperoleh dengan beberapa baris CSS dalam output HTML di atas. Yaitu:judul bagian berwarna merah dan ringkasan paragraf miring.

Trik yang saya gunakan di sini adalah membuat lembar gaya XSLT baru, mengimpor lembar gaya DocBook asli, tetapi mengganti set atribut atau templat untuk elemen yang ingin kita ubah:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:exsl="http://exslt.org/common" exclude-result-prefixes="exsl"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version='1.0'>

<!-- Import the default DocBook stylesheet for XSL-FO -->
<xsl:import href="/etc/asciidoc/docbook-xsl/fo.xsl" />

<!--
    DocBook XSL defines many attribute sets you can
    use to control the output elements
-->
<xsl:attribute-set name="section.title.level1.properties">
    <xsl:attribute name="color">#FF0000</xsl:attribute>
</xsl:attribute-set>

<!--
    For fine-grained changes, you will need to write
    or override XSLT templates just like I did it below
    for 'summary' simpara (paragraphs)
-->
<xsl:template match="simpara[@role='summary']">
  <!-- Capture inherited result -->
  <xsl:variable name="baseresult">
    <xsl:apply-imports/>
  </xsl:variable>

  <!-- Customize the result -->
  <xsl:for-each select="exsl:node-set($baseresult)/node()">
    <xsl:copy>
      <xsl:copy-of select="@*"/>
      <xsl:attribute name="font-style">italic</xsl:attribute>
      <xsl:copy-of select="node()"/>
    </xsl:copy>
  </xsl:for-each>
</xsl:template>


</xsl:stylesheet>

Kemudian, Anda harus meminta a2x untuk menggunakan stylesheet XSL khusus untuk menghasilkan output daripada yang default menggunakan --xsl-file pilihan:

a2x -v --format pdf \
    --fop \
    --xsl-file=./custom.xsl \
    asciidoc.txt

Dengan sedikit keakraban dengan XSLT, petunjuk yang diberikan di sini dan beberapa pertanyaan di mesin pencari favorit Anda, saya pikir Anda harus dapat mulai menyesuaikan keluaran XSL-FO.

Tapi saya tidak akan berbohong, beberapa perubahan yang tampaknya sederhana dalam output dokumen mungkin mengharuskan Anda untuk menghabiskan beberapa waktu mencari melalui manual DocBook XML dan XSL-FO, memeriksa sumber stylesheet dan melakukan beberapa tes sebelum Anda akhirnya mencapai apa yang Anda inginkan .

Pendapat saya

Menulis dokumen menggunakan format teks memiliki keuntungan yang luar biasa. Dan jika Anda perlu mempublikasikan ke HTML, tidak ada banyak alasan untuk tidak menggunakan AsciiDoc. Sintaksnya bersih dan rapi, pemrosesannya sederhana dan mengubah presentasi jika diperlukan, sebagian besar membutuhkan keterampilan CSS yang mudah diperoleh.

Dan bahkan jika Anda tidak menggunakan output HTML secara langsung, HTML dapat digunakan sebagai format pertukaran dengan banyak aplikasi WYSIWYG saat ini. Sebagai contoh, ini yang telah saya lakukan di sini:Saya menyalin output HTML dari artikel ini ke dalam area edisi WordPress, sehingga menghemat semua format, tanpa harus mengetikkan apa pun langsung ke WordPress.

Jika Anda perlu mempublikasikan ke PDF— keuntungan tetap sama bagi penulis. Hal-hal pasti akan lebih sulit jika Anda perlu mengubah tata letak default secara mendalam. Dalam lingkungan korporat, itu mungkin berarti menyewa dokumen yang dirancang terampil dengan XSLT untuk menghasilkan kumpulan lembar gaya yang sesuai dengan kebutuhan merek atau teknis Anda— atau bagi seseorang dalam tim untuk memperoleh keterampilan tersebut. Tetapi setelah selesai, akan menyenangkan untuk menulis teks dengan AsciiDoc. Dan melihat tulisan-tulisan itu secara otomatis dikonversi ke halaman HTML atau dokumen PDF yang indah!

Terakhir, jika Anda menemukan AsciiDoc terlalu sederhana atau terlalu rumit, Anda dapat melihat beberapa format file lain dengan tujuan yang sama:Markdown, Textile, reStructuredText atau AsciiDoctor. Bahkan jika didasarkan pada konsep sejak awal komputasi, ekosistem format teks yang dapat dibaca manusia cukup kaya. Mungkin lebih kaya itu hanya 20 tahun yang lalu. Sebagai bukti, banyak generator situs web statis modern didasarkan pada mereka. Sayangnya, ini di luar cakupan artikel ini. Jadi, beri tahu kami jika Anda ingin mendengar lebih banyak tentang itu!