Volledige handleiding voor het gebruik van AsciiDoc in Linux

Brief: Deze gedetailleerde gids bespreekt de voordelen van het gebruik van AsciiDoc en laat zien hoe AsciiDoc in Linux moet worden geïnstalleerd en gebruikt.

In de loop der jaren heb ik veel verschillende tools gebruikt om artikelen, rapporten of documentatie te schrijven. Ik denk dat alles voor mij begon met Luc Barthelet's Epistole op Apple IIc van de Franse editor Version Soft. Daarna schakelde ik over op GUI-tools met het uitstekende Microsoft Word 5 voor Apple Macintosh, en vervolgens het minder overtuigende (voor mij) StarOffice op Sparc Solaris, dat al bekend stond als OpenOffice toen ik definitief naar Linux overschakelde. Al deze tools waren echt tekstverwerkers.

Maar ik was nooit echt overtuigd door WYSIWYG-editors. Dus onderzocht ik veel verschillende min of meer door mensen leesbare tekstformaten: troff, HTML, RTF, TeX / LaTeX, XML en tot slot AsciiDoc, het gereedschap dat ik vandaag het meest gebruik. In feite gebruik ik het nu om dit artikel te schrijven!

Als ik die geschiedenis maakte, was dat omdat de lus op de een of andere manier gesloten is. Epistole was een tekstverwerker van het tekstconsoletijdperk. Voor zover ik me herinner, waren er menu's en je kunt de muis gebruiken om tekst te selecteren - maar de meeste opmaak werd gedaan door niet-intrusieve tags toe te voegen aan de tekst. Net zoals het gedaan is met AsciiDoc. Het was natuurlijk niet de eerste software om dat te doen. Maar het was de eerste die ik gebruikte!

Waarom AsciiDoc (of een ander tekstbestandsformaat)?

Ik zie twee voordelen bij het gebruik van tekstformaten om te schrijven: ten eerste is er een duidelijke scheiding tussen de inhoud en de presentatie. Dit argument is bespreekbaar omdat sommige tekstformaten zoals TeX of HTML een goede discipline vereisen om zich aan die scheiding te houden. En aan de andere kant kun je op een of andere manier een zekere mate van scheiding bereiken door sjablonen en stylesheets te gebruiken met WYSIWYG-editors. Daar ben ik het mee eens. Maar ik vind presentatieproblemen nog steeds opdringerig met GUI-tools. Terwijl, bij het gebruik van tekstformaten, je je alleen op de inhoud kunt concentreren zonder dat je een letterstijl of een weduwenlijn gebruikt die je schrijfproces verstoren. Maar misschien is het alleen mij? Ik kan echter niet het aantal keren tellen dat ik mijn schrijven stopte alleen om een ​​klein probleem met de styling op te lossen - en mijn inspiratie verloren toen ik terugkwam naar de tekst. Als je het niet eens bent of een andere ervaring hebt, aarzel dan niet om me tegen te spreken met behulp van de commentaarsectie hieronder!

Hoe dan ook, mijn tweede argument zal minder onderhevig zijn aan persoonlijke interpretatie: documenten op basis van tekstformaten zijn zeer interoperabel . U kunt ze niet alleen met elke teksteditor op elk platform bewerken, maar u kunt eenvoudig tekstherzieningen beheren met een tool zoals git of SVN, of tekstwijzigingen automatiseren met behulp van algemene tools zoals sed, AWK, Perl enzovoort. Om u een concreet voorbeeld te geven, bij het gebruik van een op tekst gebaseerde indeling zoals AsciiDoc, heb ik slechts één opdracht nodig om zeer gepersonaliseerde mailing te produceren vanuit een origineel document, terwijl dezelfde taak met een WYSIWYG-editor een slim gebruik van "velden" zou vereisen en door verschillende wizardschermen gaan.

Wat is AsciiDoc?

Strikt genomen is AsciiDoc een bestandsformaat. Het definieert syntactische constructies die een processor helpen de semantiek van de verschillende delen van uw tekst te begrijpen. Meestal om een ​​mooi geformatteerde uitvoer te produceren.

Zelfs als die definitie abstract zou kunnen lijken, is dit iets eenvoudigs: sommige trefwoorden of tekens in uw document hebben een speciale betekenis die de weergave van het document zal veranderen. Dit is exact hetzelfde concept als de tags in HTML. Maar een belangrijk verschil met AsciiDoc is dat de eigendom van het brondocument gemakkelijk leesbaar voor de mens blijft.

Bekijk onze GitHub-repository om te vergelijken hoe dezelfde output kan worden geproduceerd met behulp van een paar veelgebruikte tekstbestandsindelingen: (koffie manpage-idee met dank aan //www.linuxjournal.com/article/1158)

  • coffee.man gebruikt de eerbiedwaardige troff- processor (gebaseerd op het 1964 RUNOFF-programma). Het wordt tegenwoordig het meest gebruikt om manpagina's te schrijven. Je kunt het proberen nadat je de coffee.* man ./coffee.man gedownload door man ./coffee.man achter je opdrachtprompt te typen.
  • coffee.tex gebruikt de LaTeX- syntaxis (1985) om grotendeels hetzelfde resultaat te bereiken, maar dan voor een PDF-uitvoer. LaTeX is een zetprogramma dat vooral geschikt is voor wetenschappelijke publicaties vanwege het vermogen om wiskundige formules en tabellen op een mooie manier op te maken. U kunt de PDF van de LaTeX-bron produceren met pdflatex coffee.tex
  • coffee.html gebruikt het HTML-formaat (1991) om de pagina te beschrijven. U kunt dat bestand rechtstreeks openen met uw favoriete webbrowser om het resultaat te zien.
  • coffee.adoc, tenslotte, gebruikt de AsciiDoc-syntaxis (2002). U kunt zowel HTML als PDF uit dat bestand maken:
 asciidoc coffee.adoc # HTML output a2x --format pdf ./coffee.adoc # PDF output (dblatex) a2x --fop --format pdf ./coffee.adoc # PDF output (Apache FOP) 

Nu hebt u het resultaat gezien, opent u deze vier bestanden met uw favoriete teksteditor (nano, vim, SublimeText, gedit, Atom, ...) en vergelijkt u de bronnen: er zijn grote kansen dat u het ermee eens bent dat de AsciiDoc-bronnen gemakkelijker te lezen zijn - en waarschijnlijk ook om te schrijven.

Hoe AsciiDoc in Linux te installeren?

AsciiDoc is relatief complex om te installeren vanwege de vele afhankelijkheden. Ik bedoel complex als je het uit bronnen wilt installeren. Voor de meesten van ons is het gebruik van onze pakketbeheerder waarschijnlijk de beste manier:

 apt-get install asciidoc fop 

of de volgende opdracht:

 yum install acsiidoc fop 

(fop is alleen nodig als je de Apache FOP-backend voor PDF-generatie nodig hebt - dit is de PDF-backend die ik zelf gebruik)

Meer informatie over de installatie is te vinden op de officiële AsciiDoc-website. Voor nu is alles wat je nu nodig hebt een beetje geduld, omdat, althans op mijn minimale Debian-systeem, het installeren van AsciiDoc 360 MB vereist om te downloaden (voornamelijk vanwege de LaTeX-afhankelijkheid). Die, afhankelijk van je internetbandbreedte, je genoeg tijd kan geven om de rest van dit artikel te lezen.

AsciiDoc Handleiding: Hoe te schrijven in AsciiDoc?

Ik heb het verschillende keren gezegd, AsciiDoc is een door mensen leesbaar tekstbestandsformaat . U kunt uw documenten dus schrijven met de teksteditor van uw keuze. Er zijn zelfs speciale teksteditors. Maar ik zal hier niet over ze praten, gewoon omdat ik ze niet gebruik. Maar als u er een gebruikt, aarzel dan niet om uw feedback te delen met behulp van de opmerkingen aan het einde van dit artikel.

Ik ben niet van plan hier nog een andere syntaxis-tutorial van AsciiDoc te maken: er zijn er al genoeg beschikbaar op het web. Dus ik zal alleen de zeer basale syntactische constructies noemen die je in vrijwel elk document zult gebruiken. Uit het bovenstaande eenvoudige voorbeeld van "koffie" kunt u het volgende zien:

  • titels in AsciiDoc worden geïdentificeerd door ze te baseren op === of --- (afhankelijk van het titelniveau),
  • vetgedrukte karakterlengtes worden tussen starts geschreven,
  • en cursief tussen onderstrepingstekens.

Dat is een vrij algemene conventie die waarschijnlijk stamt uit het pre-HTML-e-mailtijdperk. Bovendien hebt u wellicht twee andere veel voorkomende constructies nodig, die niet in mijn vorige voorbeeld zijn geïllustreerd: hyperlinks en afbeeldingen- insluiting, waarvan de syntaxis redelijk voor de hand ligt.

 // 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] 

Maar de syntaxis van AsciiDoc is veel rijker dan dat. Als je meer wilt, kan ik je naar die leuke AsciiDoc cheatsheet verwijzen: //powerman.name/doc/asciidoc

Hoe render je de uiteindelijke uitvoer?

Ik ga ervan uit dat je hier al wat tekst hebt geschreven volgens het AsciiDoc-formaat. Als dit niet het geval is, kunt u hier enkele voorbeeldbestanden downloaden die rechtstreeks uit de AsciiDoc-documentatie zijn gekopieerd:

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

Aangezien AsciiDoc voor de mens leesbaar is, kunt u de AsciiDoc-brontekst rechtstreeks per e-mail naar iemand sturen, en de ontvanger kan dat bericht zonder meer lezen. Maar misschien wilt u nog wat netter geformatteerde uitvoer opgeven. Bijvoorbeeld als HTML voor webpublicatie (net zoals ik het voor dit artikel heb gedaan). Of als PDF om te printen of weer te geven.

In alle gevallen heb je een processor nodig . In feite heeft u onder de motorkap meerdere processors nodig. Omdat uw AsciiDoc-document zal worden omgezet in verschillende tussenliggende formaten voordat de uiteindelijke uitvoer wordt geproduceerd. Omdat er verschillende hulpmiddelen worden gebruikt, waarvan de uitvoer de invoer is van de volgende, spreken we soms over een gereedschapskist .

Zelfs als ik hier wat innerlijke werkdetails uitleg, moet je begrijpen dat het meeste daarvan voor je verborgen zal blijven. Tenzij misschien als u in eerste instantie de hulpmiddelen moet installeren- of als u sommige stappen van het proces wilt verfijnen.

In praktijk?

Voor HTML-uitvoer hebt u alleen de asciidoc tool nodig. Voor meer gecompliceerde toolchains, moedig ik u aan om de a2x tool (onderdeel van de AsciiDoc-distributie) te gebruiken die de nodige processors in volgorde zal activeren:

 # 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 

Zelfs als het direct een HTML-uitvoer kan produceren, blijft de kernfunctionaliteit van de asciidoc tool bestaan ​​om het AsciiDoc-document te transformeren naar het intermediate DocBook-formaat. DocBook is een XML-gebaseerde indeling die vaak wordt gebruikt voor (maar niet beperkt tot) publicatie van technische documentatie. DocBook is een semantisch formaat. Dat betekent dat het uw documentinhoud beschrijft. Maar niet de presentatie ervan. Opmaak is dus de volgende stap van de transformatie. Daarvoor, ongeacht het outputformaat, wordt het DocBook-tussendocument verwerkt via een XSLT-processor om ofwel direct de uitvoer (bijv. XHTML) of een ander tussenformaat te produceren.

Dit is het geval wanneer u een PDF-document genereert waarbij het DocBook-document (naar uw wens) wordt geconverteerd als LaTeX-tussenrepresentatie of als XSL-FO (een op XML gebaseerde taal voor paginabeschrijving). Ten slotte zal een speciale tool die representatie naar PDF converteren.

De extra stappen voor PDF-generaties worden met name gerechtvaardigd door het feit dat de toolchain paginering voor de PDF-uitvoer moet verwerken. Iets wat niet nodig is voor een "stream" -formaat zoals HTML.

dblatex of fop?

Aangezien er twee PDF-backends zijn, is de gebruikelijke vraag "Welke is de beste?" Iets dat ik niet voor u kan beantwoorden.

Beide processors hebben voor- en nadelen. En uiteindelijk zal de keuze een compromis zijn tussen uw behoeften en uw voorkeuren. Dus ik moedig je aan om de tijd te nemen om beide te proberen voordat je de backend kiest die je gaat gebruiken. Als u het LaTeX-pad volgt, is dblatex de back-end die wordt gebruikt om de PDF te produceren. Het zal Apache FOP zijn als je liever het XSL-FO tussenformaat gebruikt. Vergeet dus niet om de documentatie van deze tools te bekijken om te zien hoe gemakkelijk het is om de uitvoer aan uw behoeften aan te passen. Tenzij je natuurlijk tevreden bent met de standaard uitvoer!

Hoe de uitvoer van AsciiDoc aanpassen?

AsciiDoc naar HTML

Out-of-the-box, produceert AsciiDoc best mooie documenten. Maar vroeg of laat zult u wat hun uiterlijk aanpassen.

De exacte wijzigingen zijn afhankelijk van de back-end die u gebruikt. Voor de HTML-uitvoer kunnen de meeste wijzigingen worden aangebracht door de CSS-stylesheet te wijzigen die aan het document is gekoppeld.

Stel dat ik bijvoorbeeld alle sectiekoppen rood wil weergeven, dan zou ik het volgende custom.css bestand kunnen maken:

 h2 { color: red; } 

En verwerk het document met de licht gewijzigde opdracht:

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

U kunt ook wijzigingen aanbrengen op een fijner niveau door een rolattribuut aan een element te koppelen. Dit vertaalt zich naar een class- kenmerk in de gegenereerde HTML.

Probeer bijvoorbeeld ons testdocument te wijzigen om het rolkenmerk toe te voegen aan de eerste alinea van de tekst:

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

Voeg vervolgens de volgende regel toe aan het bestand custom.css :

 .summary { font-style: italic; } 

Genereer het document opnieuw:

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

  1. et voila: de eerste alinea wordt nu cursief weergegeven. Met een beetje creativiteit, wat geduld en een paar CSS-tutorials, zou je je document naar wens kunnen aanpassen.

AsciiDoc naar PDF

Het aanpassen van de PDF-uitvoer is iets complexer. Niet vanuit het perspectief van de auteur, aangezien de brontekst identiek zal blijven. Uiteindelijk gebruikt u hetzelfde rolattribuut als hierboven om de onderdelen te identificeren die een speciale behandeling nodig hebben.

U kunt CSS echter niet langer gebruiken om de opmaak voor PDF-uitvoer te definiëren. Voor de meest voorkomende instellingen zijn er parameters die u kunt instellen vanaf de opdrachtregel. Sommige parameters kunnen zowel met de dblatex- als de fop- backends worden gebruikt, andere zijn specifiek voor elke backend.

Zie //dblatex.sourceforge.net/doc/manual/sec-params.html voor de lijst met door dblatex ondersteunde parameters.

Zie //docbook.sourceforge.net/release/xsl/1.75.2/doc/param.html voor de lijst met DocBook XSL-parameters.

Aangezien margestijging een vrij algemene vereiste is, kunt u ook een kijkje nemen op dat: //docbook.sourceforge.net/release/xsl/current/doc/fo/general.html

Als de parameternamen enigszins consistent zijn tussen de twee backends, verschillen de opdrachtregelargumenten die worden gebruikt om die waarden door te geven aan de backends tussen dblatex en fop . Controleer dus eerst uw syntaxis als dit blijkbaar niet werkt. Maar om eerlijk te zijn, tijdens het schrijven van dit artikel kon ik de body.font.family werken met de dblatex- backend. Omdat ik meestal fop gebruik, heb ik misschien iets gemist? Als je daar meer aanwijzingen over hebt, lees ik graag je suggesties in het commentaargedeelte aan het einde van dit artikel!

Het vermelden waard met niet-standaard lettertypen - zelfs met fop - vereist wat extra werk. Maar het is behoorlijk goed gedocumenteerd op de Apache-website: //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 

Fijnmazig instelling voor het genereren van PDF's

Globale parameters zijn leuk als je alleen een aantal vooraf gedefinieerde instellingen moet aanpassen. Maar als u het document nauwkeurig wilt afstemmen (of de lay-out volledig wilt wijzigen), hebt u extra inspanningen nodig.

De kern van de DocBook-verwerking is XSLT. XSLT is een computertaal, uitgedrukt in XML-notatie, waarmee willekeurige transformatie van een XML-document naar ... iets anders kan worden geschreven. XML of niet.

U moet bijvoorbeeld de DocBook XSL-stylesheet uitbreiden of wijzigen om de XSL-FO-code te produceren voor de nieuwe stijlen die u mogelijk wilt. En als u de dblatex- backend gebruikt, moet u mogelijk de bijbehorende DocBook-naar-LaTeX XSLT-stylesheet aanpassen. In dat laatste geval moet u mogelijk ook een aangepast LaTeX-pakket gebruiken. Maar daar zal ik niet op focussen, omdat dblatex niet de backend is die ik zelf gebruik. Ik kan u alleen naar de officiële documentatie verwijzen als u meer wilt weten. Maar nogmaals, als u hiermee bekend bent, deel dan uw tips en trucs in de commentaarsectie!

Zelfs als ik alleen maar op fop focus, heb ik hier niet echt de ruimte om de hele procedure te beschrijven. Ik zal u dus alleen de wijzigingen tonen die u zou kunnen gebruiken om een ​​vergelijkbaar resultaat te verkrijgen als het resultaat dat u hebt behaald met enkele CSS-regels in de bovenstaande HTML-uitvoer. Dat wil zeggen: sectietitels in rood en een samenvattingsparagraaf in cursief.

De truc die ik hier gebruik, is om een ​​nieuw XSLT-stylesheet te maken, het originele DocBook-stylesheet te importeren, maar de attribuutsets of -sjabloon te vervangen voor de elementen die we willen wijzigen:

  #FF0000 italic 

Vervolgens moet u a2x aanvragen om dat aangepaste XSL-stylesheet te gebruiken om de uitvoer te produceren in plaats van de standaardversie met behulp van de optie --xsl-file :

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

Met een beetje vertrouwdheid met XSLT, de hints die hier worden gegeven en enkele vragen over je favoriete zoekmachine, denk ik dat je moet kunnen beginnen met het aanpassen van de XSL-FO-uitvoer.

Maar ik zal niet liegen, sommige ogenschijnlijk eenvoudige veranderingen in de documentuitvoer kunnen vereisen dat je behoorlijk wat tijd spendeert om door de DocBook XML- en XSL-FO-handleidingen te zoeken, de stylesheetsbronnen te bekijken en een paar tests uit te voeren voordat je uiteindelijk bereikt wat je wilt .

Mijn mening

Het schrijven van documenten met een tekstformaat heeft enorme voordelen. En als u moet publiceren naar HTML, is er niet veel reden om AsciiDoc niet te gebruiken. De syntaxis is schoon en netjes, de verwerking is eenvoudig en het wijzigen van de presentatie, indien nodig, vereist meestal eenvoudig CSS-vaardigheden te verwerven.

En zelfs als u de HTML-uitvoer niet rechtstreeks gebruikt, kan HTML tegenwoordig worden gebruikt als een uitwisselingsindeling met veel WYSIWYG-toepassingen. Bijvoorbeeld, dit is wat ik hier heb gedaan: ik kopieerde de HTML-uitvoer van dit artikel naar het WordPress-uitdeelgebied, waardoor alle opmaak behouden bleef, zonder iets rechtstreeks in WordPress te hoeven typen.

Als u naar PDF moet publiceren, blijven de voordelen voor de schrijver hetzelfde. De dingen zullen zeker strenger zijn als je de standaardlay-out in de diepte moet veranderen. In een bedrijfsomgeving betekent dat waarschijnlijk het inhuren van een document dat is ontwikkeld door XSLT om de set stijlbladen te produceren die past bij uw merk- of technische vereisten, of voor iemand in het team om die vaardigheden te verwerven. Maar eenmaal gedaan is het een genot om tekst te schrijven met AsciiDoc. En het zien van die teksten die automatisch worden omgezet in prachtige HTML-pagina's of PDF-documenten!

Als u ten slotte AsciiDoc ofwel te simplistisch of te complex vindt, kunt u enkele andere bestandsindelingen met vergelijkbare doelen bekijken: Markdown, Textile, reStructuredText of AsciiDoctor om maar een paar te noemen. Zelfs als het gebaseerd is op concepten die dateren uit de begintijd van de computer, is het ecosysteem dat door mensen wordt gelezen, behoorlijk rijk. Waarschijnlijk rijker was het pas 20 jaar geleden. Als bewijs zijn veel moderne statische websitegenerators daarop gebaseerd. Helaas valt dit buiten de scope van dit artikel. Dus, laat het ons weten als je meer wilt horen!

Aanbevolen

Installeer Adobe Lightroom Alternatieve RawTherapee in Ubuntu
2019
Download 15 prachtige sexy achtergronden van Debian
2019
Gebruik de modus Niet storen in Ubuntu met NoNotifications
2019