PR#4: Added 'producing-pdf-files.adoc' - fedora-docs/documentation-contributors-guide

fedora-docs / documentation-contributors-guide

#4 Added 'producing-pdf-files.adoc'

Closed 5 years ago by ojn. Opened 5 years ago by ojn.

Unknown source pdf into master

included pdf chapter in nav

ojn • 5 years ago

f272dd9

created producing-pdf-files.adoc file

ojn • 5 years ago

f921f84

modules/contributing/nav.adoc

file modified

		`@@ -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]`

modules/contributing/pages/producing-pdf-files.adoc

file added

+119

		`@@ -0,0 +1,119 @@`
		`+ = Producing PDF files`
		`+`
		`+ There are a couple of ways to produce PDF files from Asciidoc documents:`
		`+`
		+ . Use the standard https://asciidoctor.org/[Asciidoctor toolchain] with the ``asciidoctor-pdf``
		`+`
		`+ . 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 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.`

ojn commented 5 years ago

We need to describe that pdf files should not be version controlled with git but instead created to be uploaded some other place, any ide where?

pbokoc commented 5 years ago

@ojn Hi, I found an issue - the new file modules/contributing/pages/producing-pdf-files.adoc isn't included in nav.adoc so it doesn't show up in the table of contents and it's not discoverable. Please add it there.

Also a minor problem, the PR shouldn't have included the updated scripts; I'm glad you commited them, but it should have been a separate PR. I'd say it's fine to keep it now that they're already commited, but next time please keep different updates separate.

Regarding storing PDFs - well, that's a tough one. I know binaries in repos are bad but I don't know where else to store them. Antora docs even say to store them in modules/<module>/assets, IIRC. It makes cloning take forever but the only alternative I can think of is to dump them in a directory on someone's fedorahosted space and that's a bad idea too.

rebased onto f921f84

5 years ago

ojn commented 5 years ago

it should have been a separate PR.

Yeah I know, that's my inability to use git that shows through :beginner:
I'm still trying to learn how to use branches correctly.

. It makes cloning take forever but the only alternative I can think of is to dump them in a directory on someone's fedorahosted space and that's a bad idea too.

Yeah that could be useful for drafts and previews, but for SEO perspective it needs to go on the main site. I think we would need to ask infrastucture team.
I think @asamalik was talking that CI was on the plans for the future.
I'm not a sysadmin but that would be a perfect time to think about it and opportunity to implement- how such assets can be served. Putting a reverse proxy in style with Traefik might do the trick. There seems to be a lot of knowledgeable people who like containers so we should figure out something.

1 new commit added

included pdf chapter in nav

5 years ago

bex commented 5 years ago

If the assets are generated for each version, I think they should be built and placed at publish. If they are part of hte document (i.e. an example) especially something that won't change frequently, I think, much like an image, they should be committed.

Pull-Request has been closed by ojn

5 years ago