From f921f84ad1c04b336c463ee016d5e7411bde2f5d Mon Sep 17 00:00:00 2001 From: ojn Date: Sep 25 2018 12:28:35 +0000 Subject: [PATCH 1/2] created producing-pdf-files.adoc file --- diff --git a/modules/contributing/pages/producing-pdf-files.adoc b/modules/contributing/pages/producing-pdf-files.adoc new file mode 100644 index 0000000..5fe415f --- /dev/null +++ b/modules/contributing/pages/producing-pdf-files.adoc @@ -0,0 +1,9 @@ += Producing PDF files + +There are a couple of ways to produce PDF files from Asciidoc documents: + +. Use the standard Asciidoctor toolchain with the ``asciidoctor-pdf`` + +. Convert to Docbook and use DBLatex to create the PDF files (or https://opensuse.github.io/daps/[DAPS] for a more involved process) + +. Convert to html files and create the PDF with Pupeteer (Chrome engine) or use Pandoc to create PDF form html with the help of LaTeX templates. \ No newline at end of file From f272dd939810750829e54d3f8a077e357155b9e1 Mon Sep 17 00:00:00 2001 From: ojn Date: Sep 28 2018 01:16:12 +0000 Subject: [PATCH 2/2] included pdf chapter in nav wrote about the conversion to the standard format and Asciidoctor toolchain, fixed some links --- diff --git a/modules/contributing/nav.adoc b/modules/contributing/nav.adoc index 071bbd3..86c1e97 100644 --- a/modules/contributing/nav.adoc +++ b/modules/contributing/nav.adoc @@ -4,5 +4,6 @@ ** xref:contributing-to-existing-docs.adoc[Contributing to Existing Documentation] ** xref:adding-new-docs.adoc[Adding New Documentation to the Site] ** xref:local-preview.adoc[Building a Local Preview] +** xref:producing-pdf-files.adoc[Producing PDF Files] //** xref:working-with-translations.adoc[Working with Translations] //** xref:markup.adoc[ASCIIDoc Markup] diff --git a/modules/contributing/pages/producing-pdf-files.adoc b/modules/contributing/pages/producing-pdf-files.adoc index 5fe415f..0478ee9 100644 --- a/modules/contributing/pages/producing-pdf-files.adoc +++ b/modules/contributing/pages/producing-pdf-files.adoc @@ -2,8 +2,118 @@ There are a couple of ways to produce PDF files from Asciidoc documents: -. Use the standard Asciidoctor toolchain with the ``asciidoctor-pdf`` +. Use the standard https://asciidoctor.org/[Asciidoctor toolchain] with the ``asciidoctor-pdf`` -. Convert to Docbook and use DBLatex to create the PDF files (or https://opensuse.github.io/daps/[DAPS] for a more involved process) +. Convert to Docbook and use https://pypi.org/project/dblatex/[DBLatex] to create the PDF files (or https://opensuse.github.io/daps/[DAPS] for a more involved process) -. Convert to html files and create the PDF with Pupeteer (Chrome engine) or use Pandoc to create PDF form html with the help of LaTeX templates. \ No newline at end of file +. Convert to html files and create the PDF with https://github.com/GoogleChrome/puppeteer[Pupeteer] (Chrome engine) or use https://pandoc.org/[Pandoc] to create PDF from html with the help of LaTeX templates. + +== Creating the standard structure for your document + +When you have an Antora repository that you would like to use for PDF creation, +create a new Asciidoc file at the base of the project. +Here we are calling it pages.adoc but you can call it whatever you like. +It should look something like this: + +[source, asciidoc] +---- += Pages +:toc: <1> +:img: modules/ROOT/assets/ <2> + +---- +<1> begin the file with the title and table of contents. +<2> then specify **img** directory for images that you would like to include. + +Leave one empty line and lower down add the pages in a way that is correct for Asciidoctor, +for example: + +==== ++++include::./modules/ROOT/pages/01-introduction.adoc[]+++ + ++++include::./modules/ROOT/pages/02-what-is-fedora-about.adoc[]+++ + ++++include::./modules/ROOT/pages/03-how-to-get-fedora.adoc[]+++ + ++++include::./modules/ROOT/pages/04-first-steps-in-system.adoc[]+++ + ++++include::./modules/ROOT/pages/05-how-to-tweak-fedora.adoc[]+++ + ++++include::./modules/ROOT/pages/credits.adoc[]+++ +==== + +just list all the files that you want to include. +To get the order correct use `nav.adoc` file (from modules/ROOT) as a reference on which files to include. + +When you want to specify pages that should work like subheaders in the bigger chapter use level offset. + +Here is the example that works for the template pages.adoc: + +==== ++++= Test Pizza+++ + ++++:toc:+++ + ++++:img: modules/ROOT/assets/+++ + ++++include::./modules/ROOT/pages/architecture.adoc[leveloffset=1]+++ + ++++include::./modules/ROOT/pages/pizza-owen.adoc[leveloffset=2]+++ + ++++include::./modules/ROOT/pages/pizza-dough.adoc[leveloffset=2]+++ + ++++include::./modules/ROOT/pages/community.adoc[leveloffset=1]+++ + ++++include::./modules/ROOT/pages/faq.adoc[leveloffset=1]+++ +==== + +We are using the level offset two since the second and the third files are subordinate to the first. You can notice it by the number of asterisks present on the begining of the line: + +==== ++++* xref:architecture.adoc[Architecture]+++ + ++++** xref:pizza-owen.adoc[Pizza Owen]+++ + ++++** xref:pizza-dough.adoc[Pizza Dough]+++ + ++++* xref:community.adoc[Community]+++ + ++++* xref:faq.adoc[FAQ]+++ +==== + +// TODO: describe how one fixes paths for the images + +== Installing Asciidoctor and asciidoctor-pdf + +Both are included in Fedora repositories and can be installed with: + +---- +sudo dnf install rubygem-asciidoctor && sudo dnf install rubygem-asciidoctor-pdf +---- + +To be productive with these tools you will need Bundler (that helps to integrate your build process), install it: + +---- +sudo dnf install rubygem-bundler +---- + +Next step is to initiate your project directory if you are working to create a new document; open the terminal at that directory or ``cd`` to it and do it with this command: + +---- +bundle init +---- + +Then use ``bunle add`` to attach the scripts to your project: + +---- +bundle add asciidoctor +bundle add asciidoctor-pdf +---- + +If you want to have code highlihgting add ``coderay`` in the same way after installing it: + +---- +sudo dnf install rubygem-coderay +---- + +// TODO: describe how to use bundle exec with the Makefile.