Documentation with any editor
This is a modal window.
Das Video konnte nicht geladen werden, da entweder ein Server- oder Netzwerkfehler auftrat oder das Format nicht unterstützt wird.
Formale Metadaten
| Titel |
| |
| Untertitel |
| |
| Serientitel | ||
| Anzahl der Teile | 94 | |
| Autor | ||
| Lizenz | CC-Namensnennung 4.0 International: Sie dürfen das Werk bzw. den Inhalt zu jedem legalen Zweck nutzen, verändern und in unveränderter oder veränderter Form vervielfältigen, verbreiten und öffentlich zugänglich machen, sofern Sie den Namen des Autors/Rechteinhabers in der von ihm festgelegten Weise nennen. | |
| Identifikatoren | 10.5446/45803 (DOI) | |
| Herausgeber | ||
| Erscheinungsjahr | ||
| Sprache |
Inhaltliche Metadaten
| Fachgebiet | ||
| Genre | ||
| Abstract |
|
FrOSCon 201867 / 94
3
7
9
10
13
14
16
19
21
23
25
28
29
30
31
32
33
36
37
39
40
41
43
44
46
48
49
50
53
54
57
67
75
76
77
80
81
85
90
91
92
93
00:00
TexteditorOpen SourceFreewareRechenschieberSelbst organisierendes SystemInstallation <Informatik>MultiplikationsoperatorEreignishorizontKette <Mathematik>SoftwareentwicklerKartesische KoordinatenServerXMLUMLVorlesung/Konferenz
00:50
ServerOSS <Rechnernetz>SoftwaretestDruckspannungGlobale OptimierungKernel <Informatik>SoftwareentwicklerSystemverwaltungOpen SourceInhalt <Mathematik>Graphische BenutzeroberflächeKonfiguration <Informatik>WikiElektronische PublikationMereologieKategorie <Mathematik>E-MailWort <Informatik>COMComputerGraphiktablettMobiles InternetNotebook-ComputerDateiformatFunktion <Mathematik>VersionsverwaltungKontrollstrukturInklusion <Mathematik>TaskKategorie <Mathematik>WikiProdukt <Mathematik>ServerSystemverwaltungDateiformatDatenverwaltungInhalt <Mathematik>GrenzschichtablösungKartesische KoordinatenKonfigurationsraumMereologieCodeElektronische PublikationBitFunktion <Mathematik>InformationsmanagementKonfiguration <Informatik>DistributionenraumMinimumSchnittmengeTexteditorOpen SourceInstallation <Informatik>InformationsspeicherungComputeranimation
03:58
Open SourceOffice-PaketSpezialrechnerClientInverser LimesVersionsverwaltungMobiles InternetWikiSoftwareElektronische PublikationFormale SpracheFunktion <Mathematik>KontrollstrukturE-MailZahlenbereichp-BlockCodeMailing-ListePunktBefehlsprozessorComputerNP-hartes ProblemPhysikalisches SystemOperations ResearchInformationsspeicherungPermanenteVerschlingungCross-site scriptingElement <Gruppentheorie>KonfigurationsraumVersionsverwaltungElektronische PublikationSchnittmengeSoftwareentwicklerInklusion <Mathematik>TaskKategorie <Mathematik>ZustandsmaschinePoisson-KlammerServerVerschlingungBildgebendes VerfahrenMomentenproblemOffice-PaketMultiplikationsoperatorTexteditorProgrammierungp-BlockTypentheorieWeb-SeiteHyperbelverfahrenSchreiben <Datenverarbeitung>AppletMailing-ListePunktRechenschieberDateiformatCodeDifferenteTablet PCProjektive EbeneBitSchreib-Lese-KopfZeiger <Informatik>Formale SpracheQuellcodeTouchscreenClientGleichheitszeichenPunktwolkeGrenzschichtablösungMereologieZahlenbereichWikiEinsKonfiguration <Informatik>Funktion <Mathematik>Figurierte ZahlVorlesung/KonferenzComputeranimation
10:20
BildschirmsymbolFontE-Mailp-Blockp-BlockBildschirmsymbolBildschirmfensterTwitter <Softwareplattform>Dichte <Stochastik>DifferenteVorlesung/Konferenz
11:01
Message-PassingDichte <Stochastik>p-BlockOffene MengeSchlüsselverwaltungQuellcodeFunktion <Mathematik>Dichte <Stochastik>SchlüsselverwaltungCASE <Informatik>Inklusion <Mathematik>BildschirmsymbolSkriptspracheSichtenkonzeptMomentenproblemRoutingQuellcodeSymboltabelleGamecontrollerCodeServerDateiformatComputeranimation
12:32
DateiformatFunktion <Mathematik>Dichte <Stochastik>QuellcodeVorlesung/Konferenz
13:13
Elektronische PublikationInklusion <Mathematik>MereologieGanze FunktionFlächeninhaltOffene MengeFreewareElektronische PublikationMereologieQuellcodeKonfigurationsraumDateiformatGeradeRechenschieberSymboltabelleBildgebendes VerfahrenPoisson-KlammerZahlenbereichMathematikServerp-BlockComputeranimation
14:30
Inklusion <Mathematik>SoftwaretestQuellcodep-BlockEinsVollständigkeitElektronische PublikationGeradeBefehl <Informatik>Computeranimation
15:13
Funktion <Mathematik>FreewareOpen SourceVersionsverwaltungInhalt <Mathematik>Windows ServerVariableInklusion <Mathematik>GenerizitätUmwandlungsenthalpieInstallation <Informatik>Attributierte GrammatikSpezialrechnerDateiformatRechnernetzElektronische PublikationDiagrammMIDI <Musikelektronik>DatenbankMarketinginformationssystemDatenflussFolge <Mathematik>ServerMereologieProzessautomationCoxeter-GruppeFontE-MailTranslation <Mathematik>Formale SpracheWeb-SeiteBildschirmsymbolVerzeichnisdienstDefaultGarbentheorieKonditionszahlZahlenbereichInformationSystemprogrammierungDifferenteOperations ResearchDatentypDokumentenserverBimodulKategorie <Mathematik>Elektronische PublikationRechenschieberMathematikVariableHyperbelverfahrenGeradeCodeMinimumVersionsverwaltungCoxeter-GruppeDiagrammProjektive EbeneServerDatensatzJust-in-Time-CompilerRenderingAttributierte GrammatikBildschirmfensterMultiplikationsoperatorVerschlingungBitQuellcodeKonfigurationsraumNetzbetriebssystemE-MailRechter WinkelSchreib-Lese-KopfASCIIFunktion <Mathematik>TabelleDeskriptive StatistikDichte <Stochastik>GrenzschichtablösungDeklarative ProgrammierspracheStapeldateiNabel <Mathematik>SkriptspracheZahlenbereichWeb-SeiteKartesische KoordinatenMomentenproblemHochdruckGraphenzeichnenBildgebendes VerfahrenDefaultFontDifferenzenrechnungSymboltabellePoisson-KlammerMultiplikationFormale SpracheInhalt <Mathematik>DokumentenserverClientVerzeichnisdienstBildschirmsymbolNetzadresseTexteditorPhysikalisches SystemMaßerweiterungZeitrichtungHIP <Kommunikationsprotokoll>KonditionszahlVorzeichen <Mathematik>Patch <Software>FunktionalAutomatische HandlungsplanungBestimmtheitsmaßAutorisierungVorlesung/KonferenzXML
24:20
BimodulElektronische PublikationDokumentenserverVerzeichnisdienstServerGebäude <Mathematik>Dichte <Stochastik>Coxeter-GruppeCoxeter-GruppeBimodulVersionsverwaltungMultiplikationComputerschachDokumentenserverMathematikRechenschieberProjektive EbeneKartesische KoordinatenFunktion <Mathematik>SoftwareentwicklerBitVerzeichnisdienstComputeranimation
25:41
Gebäude <Mathematik>Offene MengeKonfluenz <Informatik>WikiDichte <Stochastik>Coxeter-GruppeTexteditorSystemplattformServerFunktion <Mathematik>Dichte <Stochastik>DateiformatBenutzerbeteiligungWikiMathematikKonfiguration <Informatik>CASE <Informatik>MomentenproblemGeradeProjektive EbeneMultiplikationsoperatorCodeBrowserVisualisierungBildschirmfensterTexteditorMereologieSkriptspracheSoftwareentwicklerKette <Mathematik>Computeranimation
27:59
EntscheidungstheorieInternetworkingRechenschieberMultiplikationsoperatorVersionsverwaltungClientGrenzschichtablösungBrowserWort <Informatik>BitSoftware Development KitMobiles InternetVorlesung/Konferenz
29:06
Plug inCodeBrowserMaßerweiterungBildschirmsymbolFontOpen SourceFreewareUmsetzung <Informatik>Dichte <Stochastik>Coxeter-GruppePlastikkarteElektronische PublikationQuellcodeDeskriptive StatistikMaßerweiterungMAPVisualisierungMomentenproblemBildschirmfensterDichte <Stochastik>Projektive EbeneBrowserVerzeichnisdienstVersionsverwaltungCodePlug inNotebook-ComputerStellenringMathematikDatenverwaltungVirtuelle MaschineInstallation <Informatik>RichtungComputeranimation
31:29
Elektronische PublikationPasswortVolumenTemplateSpezialrechnerDiagrammDichte <Stochastik>DifferenteBildgebendes VerfahrenDiagrammQuellcodeVerzeichnisdienstSpezifisches VolumenDichte <Stochastik>Virtuelle MaschineThermische ZustandsgleichungFunktion <Mathematik>Umsetzung <Informatik>ProgrammierungBildschirmfensterDateiformatVorlesung/KonferenzComputeranimation
33:13
ImplementierungSchnittmengeGradientOffene MengeServerExpertensystemMAPSpezialrechnerInstallation <Informatik>VariableCachingSCI <Informatik>Prozess <Informatik>VersionsverwaltungPlug inDefaultDichte <Stochastik>Web-SeiteGeradeSystemaufrufProgrammierumgebungElektronische PublikationGenerator <Informatik>VerzeichnisdienstBenutzerbeteiligungMAPBildgebendes VerfahrenDefaultGebäude <Mathematik>ZahlenbereichVersionsverwaltungCoxeter-GruppeVerzweigendes ProgrammAbstraktionsebeneBitResultanteKonfiguration <Informatik>DateiformatMultiplikationsoperatorUmsetzung <Informatik>Lipschitz-StetigkeitSoftwaretestDichte <Stochastik>Objekt <Kategorie>Funktion <Mathematik>DokumentenserverServerCloud ComputingSkriptspracheEinsHyperbelverfahrenPunktwolkeASCIIInklusion <Mathematik>DiagrammLeistung <Physik>ZweiHinterlegungsverfahren <Kryptologie>Computeranimation
37:42
Funktion <Mathematik>DateiformatGravitationsgesetzSummierbarkeitSoftwaretestBildschirmsymbolRechnernetzPunktMailing-ListeNetzplanInformationSoftwareServerPhysikalisches SystemOperations ResearchGemeinsamer SpeicherVerzeichnisdienstFehlermeldungZahlenbereichFunktion <Mathematik>Computeranimation
38:22
VariableVersionsverwaltungServerOperations ResearchPhysikalisches SystemInformationSoftwareFunktion <Mathematik>Gemeinsamer SpeicherSoftwaretestKonditionszahlSkriptspracheAttributierte GrammatikElektronische PublikationComputervirusObjekt <Kategorie>ThreadDatenkompressionSpezialrechnerMarketinginformationssystemTrigonometrische FunktionHinterlegungsverfahren <Kryptologie>MathematikZweiMomentenproblemAggregatzustandBildgebendes VerfahrenBootenComputeranimationXML
39:15
Trigonometrische FunktionInnerer PunktVersionsverwaltungSoftwareWindows ServerServerSoftwaretestKonditionszahlVariableCase-ModdingDatenbankSicherungskopieDienst <Informatik>SpeicherabzugAuszeichnungsspracheSpezialrechnerUmsetzung <Informatik>BitHyperbelverfahrenFunktion <Mathematik>Inhalt <Mathematik>TabelleVersionsverwaltungSoftwaretestQuellcodeDichte <Stochastik>Notebook-ComputerKonditionszahlSpeicherabzugCASE <Informatik>SoundverarbeitungElektronische PublikationSoftwareAutorisierungProgramm/QuellcodeXMLJSONComputeranimation
40:36
DokumentenserverElektronische PublikationVirtuelle MaschineDateiformatStellenringService providerCASE <Informatik>Umsetzung <Informatik>Klon <Mathematik>Programm/Quellcode
41:28
Elektronische PublikationObjekt <Kategorie>SkriptspracheGradientVariableSpezialrechnerAttributierte GrammatikThreadDatenkompressionCOMComputervirusWindows ServerVersionsverwaltungServerSchedulingDatensichtgerätKommensurabilitätVariableNetzbetriebssystemVersionsverwaltungMarketinginformationssystemTabelleUmsetzung <Informatik>Inhalt <Mathematik>Dichte <Stochastik>Programm/QuellcodeComputeranimation
42:43
Coxeter-GruppeEinfügungsdämpfungDichte <Stochastik>DateiformatUmsetzung <Informatik>Wort <Informatik>Office-PaketTemplateGüte der AnpassungIdentitätsverwaltungVorlesung/Konferenz
44:13
Coxeter-GruppeDokumentenserverOffene MengeVerschlingungCheat <Computerspiel>Web logGeradeVerschlingungOffene MengeDateiformatEreignishorizontWeb logCodeMultiplikationDokumentenserverWeb-SeiteMinimumKette <Mathematik>TabelleCheat <Computerspiel>Softwareentwicklerp-BlockBitComputeranimation
46:12
QuellcodeBildgebendes VerfahrenIntegralFigurierte ZahlZahlenbereichTabelleVorlesung/Konferenz
47:02
Inklusion <Mathematik>QuellcodeFunktion <Mathematik>Spezialrechnerp-BlockCodeDateiformatBitmap-GraphikTouchscreenZahlenbereichRechenschieberFigurierte ZahlBildgebendes VerfahrenEinsPetaelektronenvoltbereichGreen-FunktionComputeranimation
47:54
Funktion <Mathematik>Gruppe <Mathematik>Menütechnikp-BlockProjektive EbeneMomentenproblemWeb-SeiteDateiformatSoftwareentwicklerKonfluenz <Informatik>BestimmtheitsmaßOrdnung <Mathematik>Produkt <Mathematik>MultiplikationsoperatorMinimalgradWikiOffice-PaketMultiplikationWeb logDefaultUmsetzung <Informatik>Einfache GenauigkeitGamecontrollerEin-AusgabeElektronische PublikationPersonal Area NetworkFront-End <Software>TabelleHeegaard-ZerlegungHochdruckSystemverwaltungVorlesung/Konferenz
52:53
FreewareOpen SourceComputeranimation
Transkript: Englisch(automatisch erzeugt)
00:07
So, welcome from me too. Today I want to start from the back of a slide deck, so first of all I want to thank you some people. First of all I thank you to my wife and my children, they were very, very patient the last weeks with me.
00:23
The organizers of FrostCon, I like that event, I'm a first-timer here, so thanks. The ASCII Doctor developers, that's one of the tools I use here. The guys from DocToolChain and all sponsors and attendees who make that possible here. So, first a sentence from me, my name is Christoph Stöttner for my daily work.
00:44
I do most of the stuff with the three-letter company there, so I'm a business partner and I do installations and configurations of application servers. I started with open source in the last 100 years, so it's in 1900.
01:08
In 1990, one of the first Linux distributions I could get my hands on and I'm a VI lover or WIM lover. I have no idea how Emacs is working, so maybe I'm too stupid, but I normally do everything with WIM.
01:24
So, when I can do it in VI, normally every editor should work. A little bit of history, what did I do or do I do for documentation?
01:41
The content is mostly configuration options, some screenshots of settings and parts of property files. And the last, let's say 15 years, I used products from Microsoft, LibreOffice, Wiki engines, Evernote, TEC, Docbook, everything worked, but I never was happy.
02:08
I hate documenting from the bottom of my heart, but the problem with, let's say, you normally start right after you're ready with your installation.
02:20
When I install a product, I need about a week, so I copy all configuration files away, I write down some notes on paper or somewhere on my notebook. And at the end of the week, I start creating the documentation for customer or for colleagues, so I normally forget something.
02:41
When I copy the configuration, it's not updated, it's outdated, I need to copy and paste it into my documents, it's just boring. So, I never had a really up-to-date documentation. What do I need in the documentation? Oh no, I forgot something here, just a disclaimer, I'm an administrator, so I have no dev background.
03:06
So, when you see code here, it should work, sometimes I don't understand why it works, but it will work. So, my needs, I want to have a searchable documentation, I want to edit on all my devices.
03:23
So, the best thing in documenting is when you do it during the install. So, I normally do an SSH to a server, and so when I can start documenting within this session, that's perfect. I need several output formats for customers, printings, product managers, and so on.
03:45
I want to have offline support because I had such things years ago that we documented in wikis, and then the server failed and the documentation, how to restore it was in that wiki. So, that's not the best way to store it. So, offline support, maybe multiple versions.
04:06
I want to have version control, even I'm not a developer, but I want to use version control like Git or something like that. And I want to include configuration settings from XML properties and so on, so from my files.
04:21
And I don't want to do a manual task to update that. I just want to have it automated. So, why did I, I think I should start, why did I stop using the other tools? Evernote was nice, it was cloud synchronized, but it never supported markdown.
04:44
They started with a new license where they limited the devices, so that was the main reason I stopped using Evernote. And the missing Linux client. Office was a compatibility thing and the licensing. Editing on different devices was horrible and I had several times things when I
05:04
just switched the printer, the images flipped around, switched to other pages and so on. It's not fun. And I had to copy and paste all stuff like my screenshots and my configuration files into the text document. So, when they change, you need to remember to exchange them in the document too.
05:27
Wikis work quite good, but editing on a mobile is sometimes not the best thing or not the most successful thing I do. I already said sometimes wiki servers are failing, so when you document in the wiki of the failing server, it's not the best way.
05:46
The syntax is different from the different versions and one of my things I want to have was I want to print the documentation or I want to give them to colleagues and customers.
06:01
So, I should have something printer friendly. And like the office thing, manual copy and paste stuff, images and configuration files. Then I started using markdown and RST, quite nice. It was human readable text, I could edit it in every editor.
06:21
There are some YCVIC editors where I can have a preview. I could type on my mobile or my tablet, it was quite good, but it was a little bit too simple. The including of property files was too complicated for me. So, I found out there is a project, Esketoc and Esketoctor, they are working on a version 2 at the moment.
06:45
I think the last stable is a 1.6 or 1.59. Here you need to just recognize Esketoc is the language definition, Esketoctor is a Ruby project to convert the sources or esky characters to an output.
07:04
It's text only, as I said it's human readable, so you can recognize it's a heading, it's a bullet point or something like that, but I can just have it in an editor. Quite simple syntax, it's not like programming Java or something like that, or like TeX, it's not that complicated, it's just some characters.
07:26
Automation a little bit later and the differences to markdown are written down in the document. I will upload the slides, so just read it there please. So, let's start with a little bit of a syntax. So, when we... is there a mouse pointer? Yeah.
07:43
So, I have two options for headings, numbered and not numbered. A heading or just equal signs, two equals is the first chapter heading. And when I want to have them numbered, there are the screenshots, numbered headings and unnumbered.
08:03
So, that's quite easy. I can use blocks and image headings, so above each file or source code or image, I can just use a dot heading or dot image
08:24
and I get a figure with a number of the image or a heading above my source code part and that's everything, that's all. A little bit of... I often use lists, so bullet points or numbered lists.
08:42
It's just starting them with a star for unnumbered lists or a dot with numbered lists, so I can just use two or three of them and I get them lined in. And last of the list ones is a definition list, so just say a word, the explanation and in HTML it renders.
09:05
That way we see here in the screenshot. Very important, including links and images, so links are just the links text and two brackets.
09:20
When I just use the link with brackets, it's the text linked to the page I link here, I can link to files too, but normally I use the HTTP here, and when I write any text into the brackets, that's the link text. So, like here, two times the same link, one time with text in the brackets, one time without,
09:43
and the rendering under that. Images, the same image, two colons, the image name and brackets is just including the image. With role, I can just add a CSS role and later write CSS code to format it.
10:04
I can give it an ID in HTML, so like here, sunset, and when I use a single colon, it's an inline image, so it will move with the text, so that's the two differences here with images.
10:22
Inline icons, I can use icons everywhere in my text, it's just use the font awesome icons, it's just icon, colon and the name of the icon, so I can use it for Twitter, Linux, Windows and so on. Very handy in the documentation, and I think one of the big advantages of AsciiDoc is an admission block,
10:46
there are different layers of them, so I have warnings, cautions, important, they are extended with an icon, I can use CSS for that, or when I use it in HTML and PDF, you see here at the left side,
11:03
an HTML rendering, at the right side, a PDF, so I always have the icon and some text. So I can just add, let's say for the customer, don't forget to back up that server, so warning symbol, don't forget back up, so one view at a A4 sheet and they see that's important.
11:23
That's experimental in the moment, I can even include buttons and menus and keys to use, or buttons to use within the document, so like an OK button, the any key or a control,
11:44
so everybody knows how to click or what to use here, sometimes needed when I can't script it. I can include any source code, so like here it's a Python code, it's just copied,
12:02
in this case it's copied to the document, there is syntax highlighting support in AsciiDoc, the syntax highlighting is working within HTML and PDF, so it's not dependent to the output format, I can just get syntax highlighting and there are three different, or I think maybe more,
12:24
highlighting engines, what we can use here, Highlight.js for HTML or Rooj Rauch for PDF and HTML, though that's handy too, yeah, normally it should be independent of the output format,
12:52
but the Highlight.js normally only works in HTML, so it's not working with PDF, so I normally use the Rauch one that should highlight in all output sources, output formats.
13:09
As I said, there I copied the source code, that's not what I want to do, I want to include it, so I normally do copy the configuration files from the server,
13:20
put it somewhere in the near of my documentation and then just include it in the documentation, so include two colons, like the image one, two colons and the path and the file name to include. When I use just the file name with brackets, it includes the entire document, that's all, with syntax highlighting, when it understands the format.
13:42
When I use lines equals, it includes the lines from, let's say, 10 to 15, there can be multiple blocks, I can say 10 to 15, comma, 20 to 22 and so on, so I can just have parts of the source code file and I can use tags,
14:02
so I can just say, okay, look in that document when there is a part with a tag, just give me the document part between the tag symbols. I'll show it on the next slide. So that's, I think, the best one because when the file changes and you get new lines, the tag one is the most useful one because you don't need to know the line numbers.
14:25
So that's the tagging, it's just a comment with tag two colons, the tag name and brackets and in the end, the end with the same tag name, there can be multiple ones in one document,
14:40
there can be a tag within another tag and when I include that, so let's say here, it includes the file name and the tags and it just, here is the example. The first source code block is the nearly complete source code of an HTML document.
15:00
In the middle, you see the include statement with the tag and in the end, you see what appears in my document after rendering, so just the four lines between the tag thing. In the last years, I normally, when I change something in a property or XML file, I said, okay, I changed something here with date and my name or my company name,
15:24
so when I searched in the file, I normally know where I edited something. Now I add the tags on top on that, so I start tag my comment and in the end, the end tag, so I know where to place and what changed or what I have changed.
15:45
A really important one, I think we saw it already in the last slides, I can use callouts in the source code. I just add a comment sign, brackets one and add the same symbol here after the four dashes,
16:03
that's the one and I just write some text under it and I just can explain that line will do this and that. So, and you see it in the bottom of that slide, on the left, that's the HTML rendering, at the right, the PDF, so it's the same, I can see it in all of my output files.
16:22
And I can explain what happens in that line and so on, or like that here, I can have multiples here. I can use variables within my ASCII doctor files, so I define just a variable with two colons, before and after, and the variable text.
16:43
Here with the callout, generic definition, I say something about the operating system is Linux here and maybe I put something in like slash, I have a property file for Windows and Linux, so I put my slash one time to slash, one time to backslash and I just use the variable in my normal code.
17:03
So that's all. Or like the, yeah, you see it here, the Windows and the Linux version, just to compare it a little bit. I would advise you, use variables in separate files. I normally write a generic file, like the main document here, there is a lot of text like
17:26
declarations of why do we something, there are schedulers, please be aware of, don't forget backup, and then I put all variables like host names, path names into my variable files.
17:41
So when I switch a documentation from one customer to another, I just need to exchange the variables because it's the same version of the server I installed. Or when I update the server version, I just need to change something in the main document and it gets the old stuff from variables, and that's all.
18:04
Conditions, very handy too. So I can say, OK, I have a variable operating system equals Linux, and then I say, OK, when the variable operating system equals Linux, please print an icon and rocks,
18:21
or when the other one comes, really, it's like that. Including diagrams, I already mentioned, it's human readable, so I can just open it in VI or any editor and change something, I can even open the text file with my mobile in any editor,
18:44
or even with a Git client which I use on my Android and commit my change and get a new updated documentation. So I can use these diagrams here, this DITAA or PlantoML,
19:01
and when you look at these examples, it's just a little bit of text and the rendering, or here, like a small network diagram with server addresses, server names, used ports and so on, just some lines of code so we can reuse it, or here, what's that, 10 lines,
19:24
and we get a rendered diagram and that's all, and we can just include it directly in the source code of the document or we can include it like before with the source code. We can use tables, important for, let's say, host names, IPs and functions, so I normally use that at one of the first chapters in my documents, just write down a pipe
19:47
and we define here, it's three columns, so all three lines are a line or a row in the table, and that's all. The percent header there just says, OK, the first line is bold, so no think about the rendering.
20:07
And now let's put everything together. I will show you a simple document and in the end we will automate it with GitLab and CI-CD to get some output. We will use ASCII Dr. Gradle for that, we use JIT or JITLab,
20:24
and here are the links for the first one, the example document, so you can look directly at the example after the session and for the presentation, even this presentation is just ASCII doc. So, let's start with the document header. That's quite important, so the first one is the title,
20:47
equals example project documentation, there's an author, an email, a revision number, revision date and the remark, we will see it later in HTML, in the bottom line in PDF, I think it's at the first or second page.
21:01
We have language, English, we will see it a little bit later. I enabled experimental for the buttons, I have a title logo to include it on the first page of my PDF output, I want to have a talk, I define a default image directory so that when I include an image,
21:25
I just write the image name and not the whole path, the doc type, icons font is like that we want to use font awesome, we want to use the source code, highlight Arush, and we want to have numbered headings.
21:42
And the last three lines are my variable files. So, just include the variables for Linux, the project and some attributes and that's pretty much all for the main document header. That's the attributes file I included in the header, it's just that when I switch the language,
22:04
that I get the right description for let's say appendix, caution, table of contents and so on. So, it translates for me, so when I use a talk, when I set language to English, I get a table of contents, when I use German, I get an Inhaltz-Werzeines, and if I use something Arabic, I get an Arabic one.
22:23
So, that's all, just switching the language is enough. The first paragraph after the header is the preface, it's just some text. I think I borrowed it from the Bob Ross Ipsum page, quite funny.
22:44
And what I want to show here is best practice for ASCII doctor is use one line per sentence. It's just, it will put it together a little bit later, so when you want to end a paragraph, you need an empty line. So, that's all.
23:02
Then I use a condition, I'm going to say, okay, when there is a version number smaller than let's say 8557 in my variables file, it shall warn my reader that he needs an update. So, we have an example for the condition here.
23:22
We want to have different operating systems, so slash and backslash, I already mentioned that. Sometimes I have script files, on Linux we use a shell extension, batch on Windows, there are different paths, the path is defined in my variable file, so I just can have a main document and updates just through switching the variable file here.
23:46
So, including configuration files. And the moment I try to get my customers using Git for everything, so the best would be to get every configuration into the version control system.
24:02
So, we create a project or a repository for let's say all XMLs in my application server and they commit it and upload them to a server where I can hopefully access it. And my documentation itself is in Git 2, so you could copy it just into your Git,
24:24
but then it's complicated to update the stuff and to get the changes back. You can use sub-modules in Git, I hope I explained it right, as I said I'm an admin. You can add sub-modules, so the version control is in that Git repository
24:41
but you include it into your directory. So, you have directly access to it, you can directly update it, you can upload, but it's not dependent on the repository you use for your application or your documentation. And you can have multiple sub-modules.
25:00
Oh, yeah, here for example it's, as I said, the document, the presentation slides, are written in SKDoc, they are converted to HTML with Reveal JavaScript and to get that, the easiest is to add the Reveal JS project as a sub-module
25:21
to my presentation slides. So, I have always the actual version of Reveal and I can just update my presentation syntax. So, now we talked about output, and I'm a little bit too fast, how we build the output and which output can we create.
25:44
I think the main outputs I use is HTML and PDF because I can print it, I can move it on a web server, I copy it to a web server and I can just have access to it. But we are not limited to that. Dogbook is a cool tool, it's sometimes complicated to write,
26:03
but when I have the format I can convert it to nearly everything. So, Dogbook is cool. EPUB, so now it's back. And there is a project which additionally uploads the output to a conference wiki
26:25
and keep it updated. I want to write that for another wiki too, but I have no time in the moment, but maybe we can do it. So, we can even write ascii-doc, upload it to any wiki engine or in that case to a conference wiki engine,
26:42
and when there is a change in our code it updates the document in the wiki. I think one of the biggest projects with the most output options is DocToolchain in the moment. I think it's mainly for developers, I use some of their scripts.
27:02
So, have a look at that, it's quite interesting. So, now after half an hour, a part of the heading of the talk, the editors. The best thing with SK Doctor is I can use any editor just writing text.
27:21
I can use my mobile, I can use VI, when I like Emacs, I use Emacs. The Windows guys maybe use Notepad++ or Visual Studio Code. I found that sentence in the documentation of SK Doctor, on Windows, stay away from Notepad and WordPad.
27:42
I think that's like talking from IE as a browser. So, I... The EE? Yeah, I know, Windows 10 has support for line endings, that's quite good now. But it's 2018 now, or...
28:02
Yeah, so it's like talking from a browser and Internet Explorer, so yeah, I never would use a WordPad for just ASCII text. But it's your decision, just use what you want. As I told you, on a mobile, I use several version control clients.
28:24
There are some for GitLab, for Git, for Bitbucket and so on. But I also have Termux on my mobile, I use directly Vim and Skit in this. I think I tweeted five, six weeks ago when I started to write the session slides.
28:43
I'm sitting in the public swimming pool, or at the public swimming pool, because I had a flu and I had to take care of my children. And I took the time and wrote the first ten slides in VI on my mobile. So, that's possible.
29:04
I think when you want to start with ASCII Doctor, you will ask for some preview. Because it's sometimes hard to write something and don't know what will be the rendering when you're ready with the document. So, with Visual Studio Code there is a already built-in preview plugin,
29:25
I think you need to additionally install it. There are browser extensions for most of the common browsers which render ASCII Doc directly. You can use a makefile, I normally use makefiles for my documents.
29:46
It's blue because it's directly linked to the actual makefile of my presentation, so just use it and have a look at that makefile. Or what I found out this week, because I needed to change some short things in that presentation,
30:02
you can just use guard and guardfile. Guard is configured that it just checks files in a directory if they are changed and when they are changed, they do something. So, I just use guard here and say when my main document changes, please run a make. And so, I just need to save the document and I got an updated version on my local notebook.
30:27
First thing of automation. So, when I want to convert the document on my local machine, I need to install ASCII Doctor.
30:43
Not very complicated, it's a Ruby project, so you can install it with Ruby champs or a package manager on Linux and Mac, it's just easy on Windows. I never tried it, but there is an installation description for Windows and then converts the stuff on the command line.
31:01
So, just ASCII Doctor and your source file and you will get an HTML. Or when you say ASCII Doctor dash PDF and the source file, you get the PDF document. That's all for now. Problem is sometimes the dependencies, just installing dependencies for Ruby and that stuff.
31:24
I had problems with that months ago and the moment it's working, I hope it stays in that level. But what's more easy is just use Docker. So, you can download a Docker ASCII Doctor image and use that.
31:42
So, the main advantage here is the dependencies are already included, everything is installed and you can use it directly in the directory where your source code is staying. When we look at the Docker command, we use a Docker run here, whereas dash dash rm means nothing else, that when the container ends running, it just gets deleted.
32:07
So, we are free from that container. Minus v is a volume, so we use $pvt, so the actual folder I'm staying when I start the program is mapped internally in the container to slash documents
32:23
and slash documents is that what ASCII Doctor will later use for the conversion. The callout 3 is just the container name, the Docker image name and 4 and 5 is the command which will run in the Docker container.
32:42
So, we will run here ASCII Doctor main.adoc. So, it will generate a document main.html and I'm done. No dependencies, just having Docker on my machine, Windows, Linux and so on.
33:01
It supports different outputs, I can use HTML, I can use HTML with diagram, I can convert to PDF and so on. The main things, I can use Docbook here as an output format. But the most powerful thing for ASCII Doctor conversion is using Gradle.
33:26
I have no clue what that really is. I know it's based on Groovy. I can read some of the lines in the documents, but I hope they just work. There is already an example directory, ASCII Doctor Gradle examples,
33:42
where you can see how to convert, let's say, ASCII Doctor to PDF with Gradle or creating presentations with Gradle. The main advantage of Gradle is I mustn't think about dependencies. Gradle will download all packages and use them for conversion.
34:05
And so, I can reuse them for my DevOps stuff. So, I just can run a Docker container on any cloud provider, get the stuff and convert my documents. And we will see it a little bit later. So, I think I wrote in my session abstract that I show Jenkins.
34:27
I had no time last week to install Jenkins, so I use GitLab because there is everything included. I will use the CI-CD pipeline from GitLab, it's free. You can use it, I think there is an installation object
34:41
option to install it in your environment or you just use the GitLab.com web page. Gradle is supported in all bigger environments for pipelines. So, you can use Gradle with Jenkins, with Travis or with the GitLab stuff. So, everything is the same. We will see an example with GitLab in that talk.
35:06
What will happen? It will convert after each commit. So, when I commit in my master branch, it will run that pipeline and I will get the result back as a download.
35:21
The results can trigger something else. So, when we get, let's say, HTML as an output, we can just upload it to a web server or something like that. It's just, you can automate everything there. So, we will just go until the download. We will see the document and then we need more where we want to see more.
35:42
I started a repository on GitLab, I added the CI CD pipeline and I created the GitLab CI YAML file. That's human readable text 2. You see it here, it's some lines more, but the most important ones, the Docker image we use for building the documentation.
36:04
It's the callout 1. At 2, it's a Ubuntu image, I think, or Debian. We need to install graphics because we want to convert our planned UML diagrams. So, we need to have graphics.
36:22
I installed that just into that Docker container. We name the stage build, we start the script Gradle. So, just Gradle without any option. And as artifacts, we want to get everything in the folder build docs as an artifact.
36:43
We will see that later. And that build only runs in the master branch, that master 5 here. So, that's, first of all, just copy and paste, you can reuse it here. And that's the Gradle file.
37:00
So, quite easy. I think the most important here are the version numbers. When there is a new version for Sqdocto-convert, we can just increase the numbers. And the last line is the default task, what Gradle will start. It's like make.
37:22
When we just start the command Gradle, it will do a generate HTML, generate PDF and a generate docbook. So, we get three formats where we just use Gradle here. That's the pipeline. I hope you can see it live in a second.
37:44
Callout 1, there the pipeline runs without error, so we can be sure there is an output. The number 2 is a failed one, so there was some error, maybe a syntax error or something like that. And the 3 is the download button where we can get our output.
38:05
Let's try if we can get it live on desktop. That one is, that's a document.
38:32
So, let's add one sentence, do a git commit and a git push.
38:46
So, that pushes our change to GitLab. And when we have a look at the pipeline, it should already, yeah. It arrived and has the state running.
39:04
And when we just click at the build state, we see what happens. So, in the moment that pipeline is pulling the Docker image, I hope in some seconds it will start the update and in the end it will just start the conversion. Trust me, that works.
39:21
So, maybe we will see it a little bit later, but I want to show you the output. So, that's the output from today in the morning. And there is the build stocks artifact. No, not docbook.
39:42
So, we want to see HTML we already saw. So, let's have a look at the PDF version. I included the session logo here and when we scroll down, it's just the documentation title, the author name, the version and the actual date, the table of contents.
40:04
My network plan, which is updated, my condition testing. So, we need an update and I think that's pretty much all here. We see the admonition and highlighted source code
40:23
from an external file. In that case, I think it's success. That's pretty much all. Let's have a look at the actual conversion. It's still running. Let's come back later. But it already runs the conversion.
40:42
So, what we see here is, and you can use Gradle on your local machine too. So, just install Gradle, create a build.gradle file and run Gradle on the machine. So, you can test everything and then upload it to any of the Jenkins
41:01
or Travis provider or so on and so on. I think that's too slow here. You see, I convert two documents in three formats in that case. The example and the main document. The repository on GitLab is public readable. So, have a look at it, clone it, copy it, play with it, what you like.
41:26
So, I thought I wanna show something. No, that's just the variables file. So, when we have a look at that operating system,
41:42
we should see it. Ah, it's done. So, that's the actual one. And now we have a look at the HTML version, the main one.
42:02
I think you can see it, yeah. So, the table of contents on the left side. And the HelloFrostCon at my first chapter. So, it's updated, it was live, it's working.
42:20
There's an appendix, I hope that the... Ah, there's the syntax highlighting broken, I need to rework that. Normally you should get syntax highlighting in HTML and PDF and so on. When you have Docbook conversion, you can do nearly everything. There is a tool, PenDoc, for download.
42:40
PenDoc can convert Docbook, let's say, to Visio, Microsoft Word, EPUB and I think 50 other formats. You can copy it to Markdown, to, yeah, everything that you think about. So, there is no loss in that conversion.
43:03
When I do my EskiDoc the thing, I know most of my colleagues will expect a Word document. Or something printable. So, I can just say, OK, PenDoc, convert it. I can add a template to my PDF or my Word document, so it's even...
43:22
With the corporate identity template of my company and everything is done, everybody is happy and I'm not forced to work with the office. Because that's the most horrible thing for me. As I said, a good documentation is, I think, written during an install
43:44
and not 5 or 10 days after it. Because you will forget some things. And I forgot a lot, trust me. Because I often sit at customers' desk and then I think, oh, I need to write that down or I need to write that down in the evening that I don't forget it.
44:00
Too late, 5 minutes later it's forgotten. So, write it down when you think about it. So, as I said, the presentation is EskiDoc 2. It's just text. The logo here and the text in the bottom line are four lines of code in the whole document.
44:28
So, when I go to the next conference I just need to exchange the logo on one place and I got the new design or I need to exchange, let's say, 10 lines of CSS and it's mostly branded for that company or that event where I'm arriving.
44:45
And the text at the bottom is the same. I think there was a big announcement one or two weeks ago that Fedora started moving their documentation to EskiDoc. So, Fedora has moved their complete documentation to EskiDoc format.
45:03
They're using Antora. Antora is like EskiDoctor, I think it's the same developer, but Antora goes a little bit further. They can create documentation from multiple Git repositories. So, it can just say, OK, took one of this and that
45:23
and put everything together and you have one complete document. So, when you wanna have that, have a look at Antora. Some useful links. The quick reference that you can just start writing documents.
45:40
The doc toolchain, the cheat sheet, it's two or three pages long. The documentation, I think the last one, it's a really cool blog. He writes about everything dependent to EskiDoc. He found everything, he knows the experimental stuff. That's quite cool, just read it.
46:01
And so, I'm done with the talk and open for questions. Yeah, thank you for the talk. Any questions? We have store, OK.
46:34
You put markers over an image. Is this an EskiDoc feature or did you just put these into the image by hand?
46:43
Sorry, I put... Markers, numbers, one, two, three, to explain later in the text. Over an image, not a source code. Ah, OK, yeah. The figure one. I think with CI integration or somewhere.
47:03
You talk about that one. So, the figure one thing here at the image. No, not that one. I think a few slides before where you show a screenshot from the CI tool.
47:21
The CI tool, that was nearly the end. That was this one. You put one, two, three ahead of this. Is this done with EskiDoc or just done in the image? The green numbers are EskiDoc and the red ones are from Shutter,
47:42
from my screenshot tool. That's faked, sorry. But it's a feature of Shutter, so it's a Linux screenshot tool and you can just select the numbering and click five times
48:03
and you get numbered buttons in Shutter. Yes, I just want to ask if you have used Sphinx documentation for making a documentation production. Sphinx, the question was if I used Sphinx documentation
48:24
to create documentation or I never tried it. OK, well, actually, we used it for our projects and what I missed here in EskiDoc was that you create a menu on the side
48:40
just for several, just for browsing the documentation. You can do that with Antora. That's working. So it's more admin or developer documentation.
49:01
OK, we'll have a look at it. Thanks. When you render your EskiDoc file to an HTML file,
49:25
will it be a single HTML file or can you render it into a whole bunch of HTML files which are interlinked? The default is a single HTML file but from Docbook you can do everything. So from Docbook you can do a multipatch with menu.
49:42
So that's no problem. More questions?
50:02
I normally have problems when I try to print something in order to keep the paragraphs together. So I don't split another page or table together. Can you control that? No, you can't control like in LaTeX or something like that. But you can convert your output to Tegh
50:23
and there you can do everything you want. But no, it's not done for let's say your master degree work or something like that. It's just to put stuff together and I would say my documentation is mainly something up to 25 pages.
50:42
So there is no need if there is a picture on the first page or on the second, it doesn't matter. I'm happy when my picture is there where I want to have it and not like in some products I mentioned already where the picture is just flipping around when I switch the printer.
51:01
First of all, thanks for the talk. I have two questions concerning output formats. First one, have you played with the Confluence output? No. Okay, the question was have I played with the Confluence output? No, not in the moment. I have a Confluence Wiki in my office.
51:22
I will do that the next weeks. But my main product is from another company and I would invest the time to get that running in the moment. Okay, and the other question is can you generate somewhat sane markdown for example for readme files?
51:41
So we have for example a long documentation written in EskyDoc and just dump the abstract to markdown. Just abstract. So the question is just if we can convert EskyDoc to markdown, yes. You can do that with Pandoc. So you can just Pandoc input format, EskyDoc output format markdown
52:04
and the opposite way. I migrated my blog some weeks ago from WordPress to Hugo and Hugo can work with backend markdown or with EskyDoc. So the exporter for WordPress creates markdown
52:21
so I took the markdown output, moved that or converted that to EskyDoc and now everything I have from my blog is in EskyDoc and Hugo. So, thanks. No questions? I don't see anything anymore but I think it was a lot of questions
52:43
so there was quite some interest in your talk. Thank you again. So, see you in the evening. Have fun.