Пълно ръководство за използване на AsciiDoc в Linux

Кратко: Това подробно ръководство разглежда предимствата на използването на AsciiDoc и ви показва как да инсталирате и използвате AsciiDoc в Linux.

През годините използвах много различни инструменти за писане на статии, доклади или документация. Мисля, че всичко започна за мен с Epistole на Luc Barthelet на Apple IIc от френския редактор Version Soft. След това преминах на GUI инструменти с отличната Microsoft Word 5 за Apple Macintosh, след това по-малко убедителна (за мен) StarOffice на Sparc Solaris, която вече беше известна като OpenOffice, когато окончателно преминах към Linux. Всички тези инструменти бяха наистина текстообработващи.

Но никога не съм бил убеден от редактори на WYSIWYG. Затова изследвах много различни текстови формати с повече или по-малко четене от хора: troff, HTML, RTF, TeX / LaTeX, XML и накрая AsciiDoc, който е най-използваният днес инструмент. Всъщност, аз го използвам точно сега, за да напиша тази статия!

Ако съм направил тази история, това е защото някак си цикъла е затворен. Epistole е текстообработваща технология в ерата на текстовата конзола. Доколкото си спомням, имаше менюта и можете да използвате мишката, за да изберете текст - но по-голямата част от форматирането е направено чрез добавяне на ненатрапчиви маркери в текста. Точно както е направено с AsciiDoc. Разбира се, това не беше първият софтуер, който да направи това. Но това беше първото, което използвах!

Защо AsciiDoc (или друг формат на текстов файл)?

Виждам две предимства при използването на текстови формати за писане: първо, има ясно разграничение между съдържанието и представянето. Този аргумент е отворен за дискусия, тъй като някои текстови формати като TeX или HTML изискват добра дисциплина, за да се придържат към това разделяне. От друга страна, можете по някакъв начин да постигнете някакво ниво на разделяне, като използвате шаблони и стилове с редактори WYSIWYG. Съгласен съм с това. Но все още намирам въпросите за представянето натрапчиви с GUI инструменти. Като се има предвид, че при използване на текстови формати, можете да се съсредоточите върху съдържанието само без какъвто и да е стил на шрифт или вдовица, които да ви смущават в писането. Но може би това е само аз? Въпреки това, не мога да преброя колко пъти съм спирал да пиша, само за да поправя някакъв малък стайлинг - и след като се върнах към текста, загубих вдъхновението си. Ако не сте съгласни или имате различен опит, не се колебайте да ми противоречите, като използвате раздела за коментари по-долу!

Както и да е, вторият ми аргумент ще бъде по-малко обект на лична интерпретация: документите, базирани на текстови формати, са силно взаимодействащи . Не само можете да ги редактирате с всеки текстов редактор на която и да е платформа, но и лесно можете да управлявате текстовите ревизии с инструмент като git или SVN, или да автоматизирате текстовите промени, като използвате общи инструменти като sed, AWK, Perl и т.н. За да ви дам конкретен пример, когато използваме текстов формат като AsciiDoc, ми е необходима само една команда, за да произвеждам високо персонализирана поща от главен документ, докато една и съща работа с WYSIWYG редактор би изисквала интелигентно използване на „полета“ и преминава през няколко екрана на съветника.

Какво представлява AsciiDoc?

Строго погледнато, AsciiDoc е файлов формат. Той дефинира синтактични конструкции, които ще помогнат на процесора да разбере семантиката на различните части на текста. Обикновено, за да се получи добре форматиран изход.

Дори ако това определение може да изглежда абстрактно, това е нещо просто: някои ключови думи или знаци в документа имат специално значение, което ще промени представянето на документа. Това е същата концепция като етикетите в HTML. Но ключова разлика с AsciiDoc е свойството на изходния документ да остане лесно четливо за човека.

Проверете нашия GitHub хранилище, за да сравните как може да бъде произведен един и същ изход, използвайки няколко обикновени текстови файла: (идеята за кафето е любезно предоставена от http://www.linuxjournal.com/article/1158)

  • coffee.man използва уважавания troff процесор (базиран на програмата RUNOFF от 1964 г.). Днес най-често се използва за писане на мъжки страници. Можете да го изпробвате, след като сте изтеглили файловете за coffee.* напишете man ./coffee.man в командния ред.
  • coffee.tex използва синтаксиса на LaTeX (1985), за да постигне най-вече същия резултат, но за PDF изход. LaTeX е набор от програми, особено подходящ за научни публикации, поради способността му да форматира математически формули и таблици. Можете да създадете PDF файла от източника LaTeX, като използвате pdflatex coffee.tex
  • coffee.html използва HTML формата (1991), за да опише страницата. Можете директно да отворите този файл с любимия си уеб браузър, за да видите резултата.
  • coffee.adoc, накрая, използва синтаксиса на AsciiDoc (2002). Можете да създадете както HTML, така и PDF от този файл:
 asciidoc coffee.adoc # HTML output a2x --format pdf ./coffee.adoc # PDF output (dblatex) a2x --fop --format pdf ./coffee.adoc # PDF output (Apache FOP) 

Сега сте видели резултата, отворете тези четири файла, като използвате любимия си текстов редактор (nano, vim, SublimeText, gedit, Atom, …) и сравнете източниците: има големи шансове да се съгласите, че източниците на AsciiDoc са по-лесни за четене - и вероятно и да пиша.

Как да инсталирате AsciiDoc в Linux?

AsciiDoc е сравнително сложен за инсталиране поради многото зависимости. Искам да кажа, комплекс, ако искате да го инсталирате от източници. За повечето от нас използването на нашия пакет мениджър вероятно е най-добрият начин:

 apt-get install asciidoc fop 

или следната команда:

 yum install acsiidoc fop 

(fop се изисква само ако имате нужда от Apache FOP бекенда за генериране на PDF - това е PDF backend, който използвам сам)

Повече подробности за инсталацията можете да намерите на официалния уебсайт на AsciiDoc. За сега всичко, от което се нуждаете сега, е малко търпение, тъй като поне на моята минимална Debian система, инсталирането на AsciiDoc изисква 360MB за изтегляне (най-вече заради зависимостта на LaTeX). Което, в зависимост от вашата интернет лента, може да ви даде достатъчно време да прочетете останалата част от тази статия.

AsciiDoc Инструкция: Как да пиша в AsciiDoc?

Аз го казах няколко пъти, AsciiDoc е формат за текстови файлове, който може да се чете от човека. Така че можете да пишете документите си чрез текстов редактор по ваш избор. Има дори и специализирани текстови редактори. Но аз няма да говоря за тях тук - просто защото не ги използвам. Но ако използвате някой от тях, не се колебайте да споделите отзивите си чрез раздела за коментари в края на тази статия.

Не възнамерявам да създавам още един урок за синтаксис на AsciiDoc: има много такива, които вече са налични в мрежата. Затова ще спомена само основните синтактични конструкции, които ще използвате в почти всеки документ. От простия пример за команда "кафе", цитиран по-горе, можете да видите:

  • заглавията в AsciiDoc се идентифицират като ги подкрепят с === или --- (в зависимост от нивото на заглавието),
  • баладните символи се записват между стартовете,
  • и курсив между долните черти.

Това са доста често срещани конвенции, които вероятно датират от ерата на електронната поща преди HTML. В допълнение, може да ви трябват още две общи конструкции, които не са илюстрирани в предишния ми пример: хипервръзки и включване на изображения, чийто синтаксис е доста очевиден.

 // HyperText links link://dashing-kazoo.flywheelsites.com[ItsFOSS Linux Blog] // Inline Images image://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo] // Block Images image:://itsfoss.com/wp-content/uploads/2017/06/itsfoss-text-logo.png[ItsFOSS Text Logo] 

Но синтаксисът на AsciiDoc е много по-богат. Ако искате повече, мога да ви насоча към тази хубава измама на AsciiDoc: //powerman.name/doc/asciidoc

Как да направим крайния резултат?

Предполагам, че вече сте написали някакъв текст, следвайки формата AsciiDoc. Ако случаят не е такъв, можете да изтеглите тук някои примерни файлове, копирани направо от документацията на AsciiDoc:

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

Тъй като AsciiDoc е четлив за човека, можете да изпратите изходния текст на AsciiDoc директно на някой по електронна поща, а получателят ще може да чете това съобщение без повече шум. Но, може да искате да предоставите малко по-добре форматиран изход. Например като HTML за уеб публикация (точно както направих за тази статия). Или като PDF за използване при отпечатване или показване.

Във всички случаи ви е необходим процесор . Всъщност под капака ще са ви необходими няколко процесора. Защото вашият AsciiDoc документ ще бъде трансформиран в различни междинни формати, преди да произведе крайния изход. Тъй като се използват няколко инструмента, изходът на един от тях е вход на следващия, понякога говорим за инструмент .

Дори да обясня тук някои вътрешни подробности, трябва да разберете, че повечето от тях ще бъдат скрити от вас. Освен ако първоначално не трябва да инсталирате инструментите - или ако искате да настроите някои стъпки от процеса.

На практика?

За HTML изход, имате нужда само от asciidoc инструмент. За по-сложни инструменти, препоръчвам ви да използвате инструмента a2x (част от дистрибуцията AsciiDoc), който ще задейства необходимите процесори, за да:

 # 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 

Дори ако може директно да произведе HTML изход, основната функционалност на инструмента asciidoc остава да трансформира AsciiDoc документа в междинния формат на DocBook. DocBook е XML-базиран формат, който обикновено се използва за (но не само) публикуване на техническа документация. DocBook е семантичен формат. Това означава, че описва съдържанието на документа ви. Но не и представянето му. Така че форматирането ще бъде следващата стъпка на трансформацията. За това, какъвто и да е изходният формат, DocBook междинният документ се обработва чрез XSLT процесор, за да произведе или директно изхода (например XHTML), или друг междинен формат.

Такъв е случаят, когато генерирате PDF документ, където документът на DocBook ще бъде (по ваше желание) конвертиран или като междинно представяне на LaTeX или като XSL-FO (XML-базиран език за описание на страницата). И накрая, специален инструмент ще преобразува това представяне в PDF.

Допълнителните стъпки за генериране на PDF файлове са особено оправдани от факта, че инструменталната верига трябва да се справя с пагинацията за PDF изхода. Нещо, което не е необходимо за „поточен“ формат като HTML.

dblatex или fop?

Тъй като има два PDF бекенда, обичайният въпрос е „Кой е най-добрият?“ Нещо, което не мога да отговоря за вас.

И двата процесора имат плюсове и минуси. И накрая, изборът ще бъде компромис между вашите нужди и вкусове. Затова ви препоръчвам да отделите време, за да опитате и двете, преди да изберете бекенда, който ще използвате. Ако следвате пътя LaTeX, dblatex ще бъде бекендът, използван за създаване на PDF. Като има предвид, че той ще бъде Apache FOP, ако предпочитате да използвате XSL-FO междинния формат. Така че не забравяйте да разгледате документацията на тези инструменти, за да видите колко лесно ще бъде да персонализирате изхода за вашите нужди. Освен ако разбира се, ако сте доволни от изход по подразбиране!

Как да персонализирате изхода на AsciiDoc?

AsciiDoc към HTML

От кутията AsciiDoc произвежда доста хубави документи. Но рано или късно ще имате какво да персонализирате външния им вид.

Точните промени ще зависят от използвания бекенд. За HTML изхода повечето промени могат да бъдат направени чрез промяна на CSS стиловете, свързани с документа.

Например, да кажем, че искам да custom.css всички заглавия на секциите в червено, мога да създам следния файл custom.css :

 h2 { color: red; } 

И обработете документа с леко променена команда:

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

Можете също така да правите промени на по-фино ниво, като прикрепите атрибут role към елемент. Това ще се превърне в атрибут на клас в генерирания HTML.

Например опитайте да промените нашия тестов документ, за да добавите атрибута за ролята към първия абзац на текста:

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

След това добавете следното правило към файла custom.css :

 .summary { font-style: italic; } 

Повторно генериране на документа:

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

  1. et voila: първият параграф сега е показан в курсив. С малко творчество, малко търпение и няколко CSS уроци, трябва да можете да персонализирате документа си по желание.

AsciiDoc to PDF

Персонализирането на PDF изхода е малко по-сложно. Не и от гледна точка на автора, тъй като изходният текст ще остане идентичен. В крайна сметка използвайки същия атрибут за роля, както по-горе, за да идентифицираме частите, които се нуждаят от специално третиране.

Но вече не можете да използвате CSS, за да дефинирате форматирането за PDF изход. За най-често срещаните настройки има параметри, които можете да зададете от командния ред. Някои параметри могат да се използват както с dblatex, така и с fop бекенда, други са специфични за всеки бекенд.

За списъка с параметри, поддържани от dblatex, вижте //dblatex.sourceforge.net/doc/manual/sec-params.html

За списъка с параметрите на DocBook XSL вижте //docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html

Тъй като корекцията на маржа е доста често срещано изискване, можете да погледнете и това: //docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

Ако имената на параметрите са донякъде последователни между двата бекенда, аргументите от командния ред, използвани за предаване на тези стойности на бекенда, се различават между dblatex и fop . Така че, проверете първо синтаксиса си, ако очевидно това не работи. Но за да бъда честен, докато пиша тази статия, не успях да направя параметъра body.font.family работи с бекенда на dblatex . Тъй като обикновено използвам fop, може би съм пропуснал нещо? Ако имате повече улики за това, аз ще съм повече от щастлив да прочета вашите предложения в раздела за коментари в края на тази статия!

Заслужава да се спомене използването на нестандартни шрифтове - дори и с fop - изискват някаква допълнителна работа. Но това е доста добре документирано на уебсайта на Apache: //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 

Фина настройка за генериране на PDF

Глобалните параметри са приятни, ако просто трябва да настроите някои предварително дефинирани настройки. Но ако искате да нагласите документа (или напълно да промените оформлението), ще се нуждаете от допълнителни усилия.

В основата на обработката на DocBook е XSLT. XSLT е компютърен език, изразен в XML нотация, който позволява да се пише произволна трансформация от XML документ в… нещо друго. XML или не.

Например, ще трябва да разширите или промените стиловата таблица на DocBook XSL, за да произведете XSL-FO кода за новите стилове, които може да искате. И ако използвате бекенда на dblatex, това може да изисква модифициране на съответната стилова таблица на DocBook-to-LaTeX XSLT. В последния случай може да се наложи да използвате персонализиран LaTeX пакет. Но аз няма да се съсредоточи върху това, тъй като dblatex не е гръб, аз се използвам. Мога само да ви насоча към официалната документация, ако искате да знаете повече. Но отново, ако сте запознати с това, моля споделете вашите съвети и трикове в секцията за коментари!

Дори докато се фокусираме само върху FOP, тук всъщност нямам място за подробности по цялата процедура. Така че, аз просто ще ви покажа промените, които бихте могли да използвате, за да получите подобен резултат като този, получен с няколко CSS реда в HTML изход по-горе. Това са: заглавия в червено и обобщен параграф в курсив.

Трикът, който използвам тук, е да създам нова XSLT стилова таблица, да импортирам оригиналния стил на DocBook, но да замествам атрибутите или шаблона за елементите, които искаме да променим:

  #FF0000 italic 

След това трябва да поискате a2x да използва тази персонализирана XSL стилова таблица, за да произведе изхода, а не по подразбиране, използвайки опцията --xsl-file :

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

С малко познаване на XSLT, намеците, дадени тук и някои заявки за любимата ви търсачка, мисля, че трябва да можете да започнете да персонализирате изхода XSL-FO.

Но аз няма да лъжа, някои очевидно прости промени в изхода на документа може да изискват от вас да прекарате доста време в търсене в DocBook XML и XSL-FO наръчниците, като изследвате източниците на стилове и извършвате няколко теста, преди най-накрая да постигнете това, което искате,

Моето мнение

Писането на документи с текстов формат има огромни предимства. И ако трябва да публикувате в HTML, няма много причини да не използвате AsciiDoc. Синтаксисът е чист и чист, обработката е проста и промяната на презентацията, ако е необходимо, най-вече изискват лесни за придобиване умения за CSS.

И дори ако не използвате директно HTML изхода, HTML може да се използва като формат за обмен с много приложения на WYSIWYG днес. Например, това е направено тук: копирах HTML изхода на тази статия в областта на WordPress изданието, като по този начин запазих цялото форматиране, без да трябва да пиша нищо директно в WordPress.

Ако трябва да публикувате в PDF - предимствата остават същите за писателя. Нещата ще бъдат определено по-сурови, ако трябва да промените подразбиращото се оформление в дълбочина. В корпоративна среда това вероятно означава наемане на документ, създаден с XSLT, за да се създаде набор от стилове, които да отговарят на вашите брандинг или технически изисквания - или някой от екипа да придобие тези умения. Но веднъж направено, ще бъде удоволствие да напишете текст с AsciiDoc. И виждайки тези писания автоматично да се конвертират в красиви HTML страници или PDF документи!

И накрая, ако откриете, че AsciiDoc е твърде опростен или твърде сложен, можете да погледнете някои други файлови формати със сходни цели: Markdown, Textile, reStructuredText или AsciiDoctor, за да посочите няколко. Дори ако се основава на концепции, датиращи от ранните дни на компютрите, екосистемата за текстов формат, която може да се чете от човека, е доста богата. Вероятно е бил по-богат само преди 20 години. Като доказателство, много модерни статични генератори на уеб сайтове са базирани на тях. За съжаление това е извън обхвата на тази статия. Затова ни уведомете, ако искате да чуете повече за това!

Препоръчано

digiKam 5.0 Издаден! Инсталирайте го в Ubuntu Linux
2019
Mycroft Mark II: Отговорът с отворен код на Amazon Echo и Google Home, който не ви шпионира
2019
13 неща, които трябва да направите след инсталирането на Ubuntu 17.04
2019