Hoe maak je een boek. Bookdown is het pakket van R waar dat mee kan. Hier enkele tips om dat te doen
Hier zie je een klein open-source boekje dat met R/RStudio, het pakket Bookdown en het programma GitHub is gemaakt. Voor deze leidraad heb ik gebruik gemaakt van een stukje stukje tekst dat Jack Dougherty and Ilya Ilyankou hebben gemaakt voor hun open-source boek link.
Ook hun boek is gemaakt met open-source-gereedschappen, het pakket Bookdown en de programma’s RStudio en GitHub. Als je in Bookdown werkt ben je als auteur in staat om met Markdown te werken (een makkelijke computer syntaxtaal om op verschillende platforms mee te lezen en te schrijven). Met die taal kun je ook publiceren in verschillende formats (HTML web-taal, PDF, ePUB en Microsoft Word documenten). Als je het boek host in een openbaar toegankelijke GitHub repository en het met GitHub Pages publiceert, wordt de tekst van het boek en het product toegankelijk op het web. Over Markdown en RMarkdown heb ik in eerdere blogs van Harrie’s hoekje geschreven. Voor de technische basisgids om met Bookdown te publiceren kunnen we verwijzen naar Yihui Xie, Bookdown: Authoring Books and Technical Documents with R Markdown, 2018, link.
Een alternatief platform voor het uitgeven van boeken is Pressbooks. Deze open-source bron van WordPress ondersteunt ook meerdere publicatie formaten (HMTL, PDF, ePUB). Auteurs kunnen gebruik maken van de betaalde hosting service http://Pressbooks.com. Gebruikers met geavanceerde WordPress-expertise en wat systeembeheervaardigheden kunnen de code ook downloaden van [link] (http://github.com/pressbooks) en hun eigen zelf gehoste boekenuitgeverij runnen.
Hieronder volgen enkele stappen die je moet zetten om een boek op te zetten zoals hierboven geformuleerd. Het zijn algemene principes die van toepassing zijn op verschillende computersytemen. Je hebt geen speciale kennis nog, maar het is allemaal makkelijker als je avontuurlijk bent of al bekend bent met R Studio, GitHub en/of computercodes.
Installeer het programma R link om jouw boek te bouwen met Bookdown. (Ja, boeken kun je ook met een statistisch pakket maken en publiceren, en het werkt!). Zie link
Is R de motor, RStudio is het dashboard voor jou. Installeer daarom de gratis RStudio Desktop versie om R gemakkelijker te gebruiken met een visuele editor link. Zie link
Selecteer in RStudio het tabblad Pakketten en selecteer Installeren. Zie link
In RStudio installeer je het ‘bookdown’-pakket om jouw boek te bouwen en gebruik je het pakket (library(bookdown). Zie link
Bookdown zou nu met succes geïnstalleerd moeten zijn in RStudio. Zie link
In RStudio installeer je ook het ‘tinytex’-pakket voor Bookdown. Daarmee kun je ook een PDF-editie van het boek te maken. Zie link
Vergeet niet: in RStudio console tinytex::install_tinytex() te typen en druk op return om de installatie te voltooien. Zie link
Ik hoop dat dit met tinytext lukt. Ikzelf werk niet met tinytex maar heb een latex-programma op mijn computer staan die de pdf-versie maakt.
Maak een gratis GitHub-account link aan om de codes te delen en online boekuitgaven te publiceren.
In jouw webbrowser, log je in op jouw GitHub account, vervolgens ga je naar de minimale repo link van de software ontwikkelaar en maak je een kopie voor jouw GitHub account. Hoe je dat doet daarover je in dit hoofdstuk link van het dataviz-boek.
Ga in je webbrowser naar het exemplaar van bookdown-minimal en klik op de groene knop Clone of Download het en selecteer Open in Desktop. Dit opent automatisch de GitHub Desktop applicatie. Zoek de code en kopieer deze naar een map op uw lokale computer.
In RStudio in de rechterbovenhoek selecteert u Project > Open Project om de bookdown-minimal map op uw lokale computer te openen. Zie link
Open in RStudio het bestand index.rmd en maak enkele eenvoudige bewerkingen op de tekst van dit minimale boek. Verwijder bijvoorbeeld het hashtag # commentaarsymbool in regel 8 om commentaar te verwijderen en activeer de optie PDF-boek. Bewaar uw bewerkingen. Zie link
Optioneel: Gebruik jouw favoriete teksteditor, bv. Atom editor link, om de tekst te wijzigen maar het kan ook goed met RStudio.
In RStudio, rechtsboven in de hoek, selecteer je de Build Book tab, selecteer je Build Book, en kies je All Formats om zowel de gitbook-stijl statische webeditie als de PDF-editie te bouwen.
Als RStudio met succes beide edities van je minimale boek bouwt, zal de output worden opgeslagen in je bookdown-minimal map. Dit wordt in een submap met de naam: _book geplaatst, omdat dit voorbeeld zo is geconfigureerd. Open ook de submap en bekijk de PDF-editie. Als RStudio fouten heeft gevonden, zullen deze in de Build viewer verschijnen. Zie link
Tip: In toekomstige sessies met RStudio moet u mogelijk het tabblad Pakketten selecteren en op Update klikken om uw softwarepakketten up-to-date te houden. Zie link
Open het GitHub-bureaublad en navigeer naar de map bookdown-minimal op uw lokale computer. Schrijf een samenvatting om de wijzigingen die u hierboven gemaakt hebt vast te leggen (op te slaan) aan uw master branch, en duw (pull) deze versie naar uw online GitHub repo. Over GitHub zal ik binnenkort nog eens een blog schrijven.
Ga in jouw webbrowser naar jouw online GitHub repo, met een webadres gelijkaardig aan https://github.com/USERNAME/bookdown-minimal (vul je GitHub gebruikersnaam in).
Scroll weer naar beneden naar deze sectie, en het webadres van uw gepubliceerde site zou moeten verschijnen. Kopieer dit adres.
Plak het webadres van bovenaf in een nieuw browsertabblad en voeg uiteindelijk _book/index.html toe, omdat dit voorbeeld is geconfigureerd om de webeditie van uw boek in deze submap op te slaan. Uw webadres moet vergelijkbaar zijn met: https://USERNAME.github.io/bookdown-minimal/_book/index.html.
Om de aangepaste instellingen voor dit boek te bekijken, ga naar de online repository https://github.com/datavizforall/dataviz-bookdown
In het _bookdown.yml bestand is de uitvoermap ingesteld om alle boekformaten in de docs map te bouwen.
https://USERNAME.github.com/REPONAMEDe meeste van de Bookdown configuratie-instellingen verschijnen in het bestand index.Rmd. Lees meer over deze opties in de technische handleiding van de software ontwikkelaar, (https://bookdown.org/yihui/bookdown/).
Daarnaast is deze GitHub Pages repo gepubliceerd met een aangepaste domeinnaam https://DataVizForAll.org. Meer informatie over de aangepaste domeinnamen vind je op https://help.github.com/articles/using-a-custom-domain-with-github-pages/, waarvoor je een domeinnaam moet kopen bij een webhostingdienst (zoals http://ReclaimHosting.com). Door het toevoegen van een GitHub Pages aangepaste domeinnaam creëer je een extra CNAME-bestand in de submap docs. Wees voorzichtig om het niet te verwijderen (of plaats een kopie in een submap voor de bewaring).
Dit boek bevat ook een aangepast 404.html-bestand dat handmatig werd overgezet naar de submap van de documenten, aangezien het niet automatisch wordt gebouwd door Bookdown.
Dit boek bevat ook een aangepaste google-analytics-datavizforall.html bestand in het root-niveau van repo (waar bookdown naar zoekt) en wordt ook handmatig overgebracht naar de docs submap (aangezien bookdown het niet lijkt te kopiëren naar daar bij elke build). Deze volgt het webverkeer met Google Analytics.
Gebruik gehoekte én ronde haakjes voor link in de tekst.
Ook, geef URL met ronde haakjes weer: (http://example.com)
Gebruik indien nodig HTML om een link te maken die in een nieuwe pagina wordt geopend.
In het index.Rmd bestand staat in de instellingen voor het webboek dat elk hoofdstuk en sectie wordt opgesplitst in een eigen HTML pagina, zonder automatische nummering. split_by: section number_sections: false
Hoofdstukken beginnen met een eerste niveau koptekst (één hashtag: #) en secties beginnen met een tweede niveau koptekst (twee hashtags: ##). Zowel de hoofdstuk- als sectietitels worden onmiddellijk gevolgd door een korte ID tussen gehoekte haakjes om kruisverwijzingen in het boek mogelijk te maken. De korte ID’s MOETEN uniek zijn, en moeten idealiter overeenkomen met de .Rmd-bestandsnaam. Hoewel elke hashtag hoofdstuk/sectie titel de standaard ID is (zoals #Inleiding in index.Rmd), is het veiliger om voor elk hoofdstuk/sectie een unieke korte ID te maken om verwarring te voorkomen.
De cursief gedrukte lijnen staan bovenaan elk hoofdstuk of sectie, met een kruisverwijzing naar de auteurspagina, gevolgd door de laatste bijgewerkte datum. Voorbeelden van hoofdstukkop, met korte ID’s, bylines en data: # Hoofdstuk Titel {#Hoofdstuk} *by[Esther Horrevorts, Hans Bellaarts](authors), last updated: June 18, 2019*
Subrubrieken binnen de hoofdstukken en secties beginnen met drie hashtags en eindigen met een symbool zonder nummering {-}.
Om een interne kruisverwijzing naar een hoofdstuk of sectie in het boek in te voegen, kun je een link invoegen met haakjes [voor de tekst] en haakjes (met de korte ID). Als verwijzing in de tekst verschijnt, voeg dan de Furfase “in dit boek” toe aan het einde van de zin, zodat we in de toekomst alle kruisverwijzingen kunnen zoeken/vinden als dat nodig is:
Zie de [GitHub tutorial](github) in het Dataviz-boek
OPMERKING: de bovenstaande verwijzingen zijn ontworpen voor het HOSTEN van WEB BOOEKEN, en werken mogelijk niet hetzelfde in lokale repo versies, of in ebook/PDF versies.