diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc index cbe13cba6e..3ad0e15b60 100644 --- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc +++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc @@ -1,247 +1,247 @@ --- title: Chapter 6. AsciiDoctor Primer prev: books/fdp-primer/doc-build next: books/fdp-primer/rosetta description: A brief introduction to AsciiDoctor tags: ["AsciiDoc", "AsciiDoctor", "Primer", "Introduction", "Guide"] showBookMenu: true weight: 7 path: "/books/fdp-primer/" --- [[asciidoctor-primer]] = AsciiDoctor Primer :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 6 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Most FDP documentation is written with AsciiDoc. This chapter explains what that means, how to read and understand the documentation source, and the techniques used. To get a complete reference of the AsciiDoctor capabilities please consult the link:https://docs.asciidoctor.org/home/[Asciidoctor documentation]. Some of the examples used in this chapter have been taken from the link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference[AsciiDoc Syntax Quick Reference]. [[asciidoctor-primer-overview]] == Overview In the original days of computers, electronic text was simple. There were a few character sets like ASCII or EBCDIC, but that was about it. Text was text, and what you saw really was what you got. No frills, no formatting, no intelligence. Inevitably, this was not enough. When text is in a machine-usable format, machines are expected to be able to use and manipulate it intelligently. Authors want to indicate that certain phrases should be emphasized, or added to a glossary, or made into hyperlinks. Filenames could be shown in a “typewriter” style font for viewing on screen, but as “italics” when printed, or any of a myriad of other options for presentation. It was once hoped that Artificial Intelligence (AI) would make this easy. The computer would read the document and automatically identify key phrases, filenames, text that the reader should type in, examples, and more. Unfortunately, real life has not happened quite like that, and computers still require assistance before they can meaningfully process text. More precisely, they need help identifying what is what. Consider this text: To remove [.filename]#/tmp/foo#, use man:rm[1]. [source,shell] ---- % rm /tmp/foo ---- It is easy for the reader to see which parts are filenames, which are commands to be typed in, which parts are references to manual pages, and so on. But the computer processing the document cannot reliably determine this. For this we need markup. The previous example is actually represented in this document like this: .... -To remove [.filename]#/tmp/foo#, use man:rm[1]. +To remove */tmp/foo*, use man:rm[1]. [source,shell] ---- % rm /tmp/foo ---- .... [[asciidoctor-headings]] == Headings AsciiDoctor supports six headings levels. If the document type is `article` only one level 0 (`=`) can be used. If the document type is `book` then there can be multiple level 0 (`=`) headings. This is an example of headings in an `article`. .... - = Document Title (Level 0) += Document Title (Level 0) - == Level 1 Section Title +== Level 1 Section Title - === Level 2 Section Title +=== Level 2 Section Title - ==== Level 3 Section Title +==== Level 3 Section Title - ===== Level 4 Section Title +===== Level 4 Section Title - ====== Level 5 Section Title +====== Level 5 Section Title - == Another Level 1 Section Title +== Another Level 1 Section Title .... [WARNING] ==== Section levels cannot be skipped when nesting sections. The following syntax is not correct. .... - = Document Title += Document Title - == Level 2 +== Level 2 - ==== Level 4 +==== Level 4 .... ==== [[asciidoctor-paragraphs]] == Paragraphs Paragraphs don't require special markup in AsciiDoc. A paragraph is defined by one or more consecutive lines of text. To create a new paragraph leave one blank line. For example, this is a heading with two paragraphs. .... - = This is the heading += This is the heading - This is the first paragraph. - This is also the first paragraph. +This is the first paragraph. +This is also the first paragraph. - And this is the second paragraph. +And this is the second paragraph. .... [[asciidoctor-lists]] == Lists AsciiDoctor supports a few types of lists, the most common are `ordered` and `unordered`. To get more information about lists, see link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[AsciiDoc Syntax Quick Reference]. [[asciidoctor-ordered-lists]] === Ordered lists To create an ordered list use the `.` character. For example, this is an ordered list. .... . First item . Second item .. Subsecond item . Third item .... And this would be rendered as. . First item . Second item .. Subsecond item . Third item [[asciidoctor-unordered-lists]] === Unordered lists To create an unordered list use the `*` character. For example, this is an unordered list. .... * First item * Second item ** Subsecond item * Third item .... And this would be rendered as. * First item * Second item ** Subsecond item * Third item [[asciidoctor-links]] == Links [[asciidoctor-links-external]] === External links To point to another website the `link` macro should be used. .... link:https://www.FreeBSD.org[FreeBSD] .... [NOTE] ==== As the AsciiDoctor documentation describes, the `link` macro is not required when the target starts with a URL scheme like `https`. However, it is a good practice to do this anyway to ensure that AsciiDoctor renders the link correctly, especially in non-latin languages like Japanese. ==== [[asciidoctor-links-internal]] === Internal link To point to another book or article the AsciiDoctor variables should be used. For example, if we are in the `cups` article and we want to point to `ipsec-must` these steps should be used. . Include the [.filename]#urls.adoc# file from [.filename]#~/doc/shared# folder. + .... \include::shared/{lang}/urls.adoc[] .... + . Then create a link using the AsciiDoctor variable to the `ipsec-must` article. + .... extref:{ipsec-must}[IPSec-Must article] .... + And this would be rendered as. + extref:{ipsec-must}[IPSec-Must article] [[asciidoctor-conclusion]] == Conclusion This is the conclusion of this AsciiDoctor primer. For reasons of space and complexity, several things have not been covered in depth (or at all). diff --git a/documentation/content/en/books/fdp-primer/doc-build/_index.adoc b/documentation/content/en/books/fdp-primer/doc-build/_index.adoc index 4b06ab4f8b..19c2b20063 100644 --- a/documentation/content/en/books/fdp-primer/doc-build/_index.adoc +++ b/documentation/content/en/books/fdp-primer/doc-build/_index.adoc @@ -1,346 +1,615 @@ --- title: Chapter 5. The FreeBSD Documentation Build Process prev: books/fdp-primer/structure next: books/fdp-primer/asciidoctor-primer description: Describes the FreeBSD Documentation Build Process tags: ["build", "process", "make"] showBookMenu: true weight: 6 path: "/books/fdp-primer/" --- [[doc-build]] = The FreeBSD Documentation Build Process :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 5 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] This chapter covers organization of the documentation build process and how man:make[1] is used to control it. [[doc-build-rendering]] == Rendering AsciiDoc into Output Different types of output can be produced from a single AsciiDoc source file. [cols="20%,20%,60%", frame="none", options="header"] |=== | Formats | File Type | Description |`html` |HTML |An `article` or `book` chapter. |`pdf` |PDF |Portable Document Format. |`epub` |EPUB |Electronic Publication. ePub file format. |=== [[doc-build-rendering-html]] === Rendering to html To render the documentation and the website to `html` use one of the following examples. [[documentation-build-example]] .Build the documentation [example] ==== [source,shell] .... % cd ~/doc/documentation % make .... ==== [[website-build-example]] .Build the website [example] ==== [source,shell] .... % cd ~/doc/website % make .... ==== [[project-build-example]] .Build the entire documentation project [example] ==== [source,shell] .... % cd ~/doc % make -j2 .... ==== Advanced build examples are given below: [[documentation-build-example-verbose]] .Build the documentation with verbose and debug messages [example] ==== [source,shell] .... % cd ~/doc/documentation % make HUGO_ARGS="--verbose --debug --path-warnings" .... ==== [[documentation-build-example-server]] .Build and serve the content with Hugo’s internal webserver [example] ==== [source,shell] .... % cd ~/doc/documentation % make run .... This webserver runs on `localhost`, port `1313` by default. To serve the content with Hugo’s internal webserver binding a specific IP address: [source,shell] .... % make run BIND=192.168.15.10 .... A `hostname` can also be set as base url to Hugo’s internal webserver: [source,shell] .... % make run BIND=192.168.15.10 HOSTNAME=example.com .... ==== [[doc-build-rendering-pdf]] === Rendering to pdf To generate a document in `pdf` format use this command. In this example the English Handbook will be used. In order to export the document correctly all the extensions should be passed using the `-r` argument. [[document-pdf-example]] .Build a document in pdf [example] ==== [source,shell] .... % cd ~/doc/documentation % asciidoctor-pdf \ -r ./shared/lib/man-macro.rb \ -r ./shared/lib/git-macro.rb \ -r ./shared/lib/packages-macro.rb \ -r ./shared/lib/inter-document-references-macro.rb \ -r ./shared/lib/sectnumoffset-treeprocessor.rb \ --doctype=book \ -a skip-front-matter \ -a pdf-theme=./themes/default-pdf-theme.yml \ -o /tmp/handbook.pdf \ content/en/books/handbook/book.adoc .... ==== [[doc-build-toolset]] == The FreeBSD Documentation Build Toolset These are the tools used to build and install the FDP documentation. * The primary build tool is man:make[1], specifically Berkeley Make. -* Python is used to generate the Table of Contents and other related Tables. * Hugo * AsciiDoctor * Git [[doc-build-makefile]] == Understanding the Makefile in the Documentation Tree There are three [.filename]#Makefile# files for building some or all of the documentation project. * The [.filename]#Makefile# in the [.filename]#documentation# directory will build only the documentation. * The [.filename]#Makefile# in the [.filename]#website# directory will build only the website. * The [.filename]#Makefile# at the top of the tree will build both the documentation and the website. The [.filename]#Makefile# appearing in subdirectories also support `make run` to serve built content with Hugo's internal webserver. This webserver runs on port 1313 by default. [[documentation-makefile]] === Documentation Makefile This [.filename]#Makefile# takes the following form: [source,shell] .... # Generate the FreeBSD documentation # # Copyright (c) 2020-2021, The FreeBSD Documentation Project # Copyright (c) 2020-2021, Sergio Carlavilla # # Targets intended for use on the command line # # all (default) - generate the books TOC and compile all the documentation -# run - serves the built documentation site for local browsing +# clean - removes generated files +# run - serves the built documentation site for local browsing +# pdf - build PDF versions of the articles and books. +# html - build HTML versions of the articles and books for +# offline use. +# If variable DOC_HTML_ARCHIVE is set, all documents will be +# archived/compressed, and only these files will be kept in the public +# directory. +# epub - build EPUB versions of the articles and books (Experimental). # # The run target uses hugo's built-in webserver to make the documentation site # available for local browsing. The documentation should have been built prior # to attempting to use the `run` target. By default, hugo will start its # webserver on port 1313. MAINTAINER=carlavilla@FreeBSD.org <.> -PYTHON_CMD = /usr/local/bin/python3 <.> -HUGO_CMD = /usr/local/bin/hugo <.> -LANGUAGES = en,es,pt_BR,de,ja,zh_CN,zh_TW,ru,el,hu,it,mn,nl,pl,fr <.> +# List of languages without book translations +ARTICLEONLY_LANGS= bn-bd da ko tr +# List of languages without article translations +BOOKONLY_LANGS= mn + +# List of all languages we have content for +ALL_LANGUAGES= bn-bd da de el en es fr hu it ja ko mn nl pl pt-br ru tr zh-cn zh-tw <.> + +LOCALBASE?= /usr/local + +RUBY_CMD = ${LOCALBASE}/bin/ruby <.> +HUGO_CMD = ${LOCALBASE}/bin/hugo <.> +HUGO_ARGS?= --verbose --minify +HUGO_OFFLINE_ARGS?= --environment offline --verbose --minify +ASCIIDOCTOR_CMD= ${LOCALBASE}/bin/asciidoctor +ASCIIDOCTORPDF_CMD= ${LOCALBASE}/bin/asciidoctor-pdf + +.if defined(DOC_LANG) && !empty(DOC_LANG) +LANGUAGES= ${DOC_LANG:S/,/ /g} +.if ${LANGUAGES:Men} == "" && ${.TARGETS:Mpdf*} == "" && ${.TARGETS:Mhtml*} == "" +.warning "Warning: cannot skip 'en'; adding it back" +LANGUAGES+= en +.endif +.else +LANGUAGES= ${ALL_LANGUAGES} +.endif + RUBYLIB = ../shared/lib .export RUBYLIB +RUN_DEPENDS= ${HUGO_CMD} \ + ${LOCALBASE}/bin/asciidoctor \ + ${LOCALBASE}/bin/rougify + .ifndef HOSTNAME -.HOST+=localhost +. ifdef BIND +.HOST=$(BIND) +. else +.HOST=localhost +. endif .else -.HOST+=$(HOSTNAME) +.HOST=$(HOSTNAME) +.endif + +# Strip the languages with only articles from the list of languages we +# will use to build books. +BOOK_LANGS= ${LANGUAGES} +.for a in ${ARTICLEONLY_LANGS} +BOOK_LANGS:= ${BOOK_LANGS:N${a}} +.endfor + +# Strip the languages with only books from the list of languages we +# will use to build articles. +ARTICLE_LANGS= ${LANGUAGES} +.for a in ${BOOKONLY_LANGS} +ARTICLE_LANGS:= ${ARTICLE_LANGS:N${a}} +.endfor + +# Take the list of all languages, and take out the ones we have been +# asked for. We'll feed this to hugo. +SKIP_LANGS= +.for a in ${ALL_LANGUAGES} +.if ${LANGUAGES:M${a}} == "" +SKIP_LANGS+= ${a} .endif +.endfor -.ORDER: all run<.> +.ORDER: all run <.> -.ORDER: starting-message generate-books-toc +.ORDER: requirements <.> +.ORDER: starting-message .ORDER: starting-message build -.ORDER: generate-books-toc build +.ORDER: build + +all: requirements starting-message generate-pgpkeys-txt build +run: requirements starting-message generate-pgpkeys-txt run-local + +# clean does not call pdf-clean as that is a subset of hugo-clean +clean: hugo-clean pgp-clean + +requirements: +.for dep in ${RUN_DEPENDS} +.if !exists(${dep}) + @(echo ${dep} not found, please run 'pkg install docproj'; exit 1) +.endif +.endfor -all: starting-message generate-books-toc build <.> +requirements-pdf: +.if !exists(${LOCALBASE}/bin/asciidoctor-pdf) + @(echo ${LOCALBASE}/bin/asciidoctor-pdf not found, please run 'pkg install rubygem-asciidoctor-pdf'; exit 1) +.endif + +requirements-epub: +.if !exists(${LOCALBASE}/bin/asciidoctor-epub3) + @(echo ${LOCALBASE}/bin/asciidoctor-epub3 not found, please run 'pkg install rubygem-asciidoctor-epub3'; exit 1) +.endif starting-message: .PHONY <.> @echo --------------------------------------------------------------- @echo Building the documentation + @echo included languages: ${LANGUAGES} + @echo excluded languages: ${SKIP_LANGS} @echo --------------------------------------------------------------- -generate-books-toc: .PHONY <.> - ${PYTHON_CMD} ./tools/books-toc-parts-creator.py -l ${LANGUAGES} - ${PYTHON_CMD} ./tools/books-toc-creator.py -l ${LANGUAGES} - ${PYTHON_CMD} ./tools/books-toc-figures-creator.py -l ${LANGUAGES} - ${PYTHON_CMD} ./tools/books-toc-tables-creator.py -l ${LANGUAGES} - ${PYTHON_CMD} ./tools/books-toc-examples-creator.py -l ${LANGUAGES} +generate-pgpkeys-txt: static/pgpkeys/pgpkeys.txt + +static/pgpkeys/pgpkeys.txt: static/pgpkeys/*key + ${RUBY_CMD} ./tools/global-pgpkeys-creator.rb -run: .PHONY <.> - ${HUGO_CMD} server -D --baseURL="http://$(.HOST):1313" +run-local: .PHONY <.> + HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} server \ + ${HUGO_ARGS} -D $(BIND:D--bind=$(BIND)) --baseURL="http://$(.HOST):1313" build: .PHONY <.> - ${HUGO_CMD} --minify + HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} ${HUGO_ARGS} + +build-offline: .PHONY + HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} ${HUGO_OFFLINE_ARGS} + +pgp-clean: .PHONY + rm -f static/pgpkeys/pgpkeys.txt + +hugo-clean: .PHONY + rm -rf resources public + +# +# PDF targets +# Use DOC_LANG to choose the language, e.g., make DOC_LANG="en fr" pdf-books +# +pdf: pdf-articles pdf-books + +pdf-books: requirements-pdf +.for _lang in ${BOOK_LANGS} + ./tools/asciidoctor.sh books ${_lang} pdf +.endfor + +pdf-articles: requirements-pdf +.for _lang in ${ARTICLE_LANGS} + ./tools/asciidoctor.sh articles ${_lang} pdf +.endfor + +pdf-clean: pdf-articles-clean pdf-books-clean + +pdf-books-clean: +.for _lang in ${BOOK_LANGS} + rm -fr ${.CURDIR}/public/${_lang}/books + -rmdir ${.CURDIR}/public/${_lang} +.endfor + -rmdir ${.CURDIR}/public/ + +pdf-articles-clean: +.for _lang in ${ARTICLE_LANGS} + rm -fr ${.CURDIR}/public/${_lang}/articles +.if !exists(${.CURDIR}/public/${_lang}/books) + rm -fr ${.CURDIR}/public/${_lang} +.endif +.endfor + -rmdir ${.CURDIR}/public + +# +# HTML targets +# +html: build-offline html-clean-global html-clean-articles html-clean-books html-archive html-archive-clean-files + +html-clean: hugo-clean + +html-clean-global: + rm -fr ${.CURDIR}/public/index.html + rm -rf pgpkeys js + +html-clean-articles: +.for _lang in ${ARTICLE_LANGS} + rm -fr ${.CURDIR}/public/${_lang}/index.html + rm -fr ${.CURDIR}/public/${_lang}/articles/index.html +.endfor + +html-clean-books: +.for _lang in ${BOOK_LANGS} + rm -fr ${.CURDIR}/public/${_lang}/books/index.html +.endfor + +html-archive: +.if defined(DOC_HTML_ARCHIVE) +.for _lang in ${ARTICLE_LANGS} + ./tools/asciidoctor.sh articles ${_lang} archive +.endfor +.for _lang in ${BOOK_LANGS} + ./tools/asciidoctor.sh books ${_lang} archive +.endfor +.endif + +html-archive-clean-files: +.if defined(DOC_HTML_ARCHIVE) + find ${.CURDIR}/public/ ! -name '*.pdf' ! -name '*.tar.gz' -type f -delete + find ${.CURDIR}/public/ -type d -empty -delete +.endif + +# +# EPUB targets +# Use DOC_LANG to choose the language, e.g., make DOC_LANG="en fr" epub-books +# +epub: epub-articles epub-books + +epub-books: requirements-epub + @echo --------------------------------------------------------------- + @echo !!! EPUB output is experimental !!! + @echo + @echo Asciidoctor EPUB3 is currently alpha software. Use accordingly. Although the + @echo bulk of AsciiDoc content is converted, there’s still work needed to fill in + @echo gaps where conversion is incomplete or unstyled. + @echo https://docs.asciidoctor.org/epub3-converter/latest/#project-status + @echo --------------------------------------------------------------- +.for _lang in ${BOOK_LANGS} + ./tools/asciidoctor.sh books ${_lang} epub +.endfor + +epub-articles: requirements-epub + @echo --------------------------------------------------------------- + @echo !!! EPUB output is experimental !!! + @echo + @echo Asciidoctor EPUB3 is currently alpha software. Use accordingly. Although the + @echo bulk of AsciiDoc content is converted, there’s still work needed to fill in + @echo gaps where conversion is incomplete or unstyled. + @echo https://docs.asciidoctor.org/epub3-converter/latest/#project-status + @echo --------------------------------------------------------------- +.for _lang in ${ARTICLE_LANGS} + ./tools/asciidoctor.sh articles ${_lang} epub +.endfor + +epub-clean: epub-articles-clean epub-books-clean + +epub-books-clean: +.for _lang in ${BOOK_LANGS} + rm -fr ${.CURDIR}/public/${_lang}/books + -rmdir ${.CURDIR}/public/${_lang} +.endfor + -rmdir ${.CURDIR}/public/ + +epub-articles-clean: +.for _lang in ${ARTICLE_LANGS} + rm -fr ${.CURDIR}/public/${_lang}/articles +.if !exists(${.CURDIR}/public/${_lang}/books) + rm -fr ${.CURDIR}/public/${_lang} +.endif +.endfor + -rmdir ${.CURDIR}/public .... <.> The `MAINTAINER` flag specifies who is the maintainer of this Makefile. -<.> `PYTHON_CMD` flag specifies the location of the Python binary. +<.> `ALL_LANGUAGES` flag specifies in which languages the table of contents has to be generated. +<.> `RUBY_CMD` flag specifies the location of the Python binary. <.> `HUGO_CMD` flag specifies the location of the Hugo binary. -<.> `LANGUAGES` flag specifies in which languages the table of contents has to be generated. <.> `.ORDER` directives are used to ensure multiple make jobs may run without problem. -<.> `all` target generates the books' tables of contents ("TOCs"), builds the documentation and puts the result in [.filename]#~/doc/documentation/public#. +<.> `all` target builds the documentation and puts the result in *~/doc/documentation/public*. <.> `starting-message` shows a message in the CLI to show the user that the process is running. -<.> `generate-books-toc` calls the scripts to generate the books TOCs. -<.> `run` runs hugo webserver on port 1313, or a random free port if that is already in use. -<.> `build` builds the documentation and puts the result in the [.filename]#~/doc/documentation/public#. +<.> `run-local` runs hugo webserver on port 1313, or a random free port if that is already in use. +<.> `build` builds the documentation and puts the result in the *~/doc/documentation/public*. [[website-makefile]] === Website Makefile This [.filename]#Makefile# takes the form of: [source,shell] .... # Generate the FreeBSD website # # Copyright (c) 2020-2021, The FreeBSD Documentation Project # Copyright (c) 2020-2021, Sergio Carlavilla # # Targets intended for use on the command line # # all (default) - generate the releases.toml and compile all the website -# run - serves the built documentation site for local browsing +# run - serves the built website for local browsing # -# The run target uses hugo's built-in webserver to make the documentation site -# available for local browsing. The documentation should have been built prior +# The run target uses hugo's built-in webserver to make the built website +# available for local browsing. The website should have been built prior # to attempting to use the `run` target. By default, hugo will start its # webserver on port 1313. MAINTAINER=carlavilla@FreeBSD.org <.> -PYTHON_CMD = /usr/local/bin/python3 <.> -HUGO_CMD = /usr/local/bin/hugo <.> +# List of all languages we have content for +ALL_LANGUAGES= de el en es fr hu it ja nl ru tr zh-cn zh-tw + +LOCALBASE?= /usr/local + +RUBY_CMD = ${LOCALBASE}/bin/ruby <.> +HUGO_CMD = ${LOCALBASE}/bin/hugo <.> +HUGO_ARGS?= --verbose RUBYLIB = ../shared/lib .export RUBYLIB .ifndef HOSTNAME -.HOST+=localhost +. ifdef BIND +.HOST=$(BIND) +. else +.HOST=localhost +. endif +.else +.HOST=$(HOSTNAME) +.endif + +.if defined(DOC_LANG) && !empty(DOC_LANG) +LANGUAGES= ${DOC_LANG:S/,/ /g} +.if ${LANGUAGES:Men} == "" +.warning "Warning: cannot skip 'en'; adding it back" +LANGUAGES+= en +.endif .else -.HOST+=$(HOSTNAME) +LANGUAGES= ${ALL_LANGUAGES} +.endif + +# Take the list of all languages, and take out the ones we have been +# asked for via DOC_LANG. We'll feed this to hugo. +SKIP_LANGS= +.for a in ${ALL_LANGUAGES} +.if ${LANGUAGES:M${a}} == "" +SKIP_LANGS+= ${a} .endif +.endfor -.ORDER: all run<.> +.ORDER: all run <.> .ORDER: starting-message generate-releases .ORDER: starting-message build .ORDER: generate-releases build +.ORDER: build post-build +.ORDER: post-build end-message -all: starting-message generate-releases run <.> +all: starting-message generate-releases build post-build end-message <.> +run: starting-message generate-releases run-local +clean: hugo-clean releases-clean starting-message: .PHONY <.> - @echo --------------------------------------------------------------- - @echo Building the website - @echo --------------------------------------------------------------- + @echo "---------------------------------------------------------------" + @echo "Building the website started on $$(date)" + @echo " included languages: ${LANGUAGES}" + @echo " excluded languages: ${SKIP_LANGS}" + @echo "---------------------------------------------------------------" + +end-message: .PHONY + @echo "---------------------------------------------------------------" + @echo "Building the website completed on $$(date)" + @echo "---------------------------------------------------------------" -generate-releases: .PHONY <.> - ${PYTHON_CMD} ./tools/releases-toml.py -p ./shared/releases.adoc +generate-releases: data/releases.toml <.> -run: .PHONY <.> - ${HUGO_CMD} server -D --baseURL="http://$(.HOST):1313" +data/releases.toml: + ${RUBY_CMD} ./tools/releases-toml.rb + +run-local: .PHONY <.> + HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} server \ + ${HUGO_ARGS} -D $(BIND:D--bind=$(BIND)) --baseURL="http://$(.HOST):1313" build: .PHONY <.> - ${HUGO_CMD} + HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} ${HUGO_ARGS} + +post-build: cgi-permissions + +cgi-permissions: + @chmod 555 ./public/cgi/*.cgi + +hugo-clean: + rm -fr public resources + +releases-clean: + rm -f data/releases.toml .... <.> The `MAINTAINER` flag specifies who is the maintainer of this Makefile. -<.> `PYTHON_CMD` flag specifies the location of the Python binary. +<.> `RUBY_CMD` flag specifies the location of the Ruby binary. <.> `HUGO_CMD` flag specifies the location of the Hugo binary. <.> `.ORDER` directives are used to ensure multiple make jobs may run without problem. -<.> `all` target builds the website and puts the result in [.filename]#~/doc/website/public#. +<.> `all` target builds the website and puts the result in *~/doc/website/public*. <.> `starting-message` shows a message in the CLI to show the user that the process is running. <.> `generate-releases` calls the script used to convert from AsciiDoc variables to TOML variables. With this conversion, the releases variables can be used in AsciiDoc and in the Hugo custom templates. -<.> `run` runs hugo webserver on port 1313, or a random free port if that is already in use. -<.> `build` builds the website and puts the result in the [.filename]#~/doc/website/public#. +<.> `run-local` runs hugo webserver on port 1313, or a random free port if that is already in use. +<.> `build` builds the website and puts the result in the *~/doc/website/public*. diff --git a/documentation/content/en/books/fdp-primer/examples/_index.adoc b/documentation/content/en/books/fdp-primer/examples/_index.adoc index d1e1acb004..55322389cf 100644 --- a/documentation/content/en/books/fdp-primer/examples/_index.adoc +++ b/documentation/content/en/books/fdp-primer/examples/_index.adoc @@ -1,160 +1,163 @@ --- title: Appendix A. Examples prev: books/fdp-primer/see-also/ description: Example of an article and a book used in the FreeBSD Documentation Project tags: ["examples", "tutorial", "AsciiDoctor", "Book", "Article"] +showBookMenu: true +weight: 15 +path: "/books/fdp-primer/" --- [appendix] [[examples]] = Examples :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: A :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] These examples are not exhaustive - they do not contain all the elements that might be desirable to use, particularly in a document's front matter. -For more examples of AsciiDoctor, examine the AsciiDoc source for this and other documents available in the Git `doc` repository, or available online starting at link:https://cgit.freebsd.org/doc/[https://cgit.freebsd.org/doc/]. +For more examples of AsciiDoctor, examine the AsciiDoc source for this and other documents available in the Git *doc* repository, or available online starting at link:https://cgit.freebsd.org/doc/[https://cgit.freebsd.org/doc/]. [[examples-asciidoctor-book]] -== AsciiDoctor `book` +== AsciiDoctor *book* -.AsciiDoctor `book` +.AsciiDoctor *book* [example] ==== [.programlisting] .... --- title: An Example Book authors: - author: The FreeBSD Documentation Project copyright: 1995-2021 The FreeBSD Documentation Project releaseinfo: "" trademarks: ["general"] --- = An Example Book :doctype: book :toc: macro :toclevels: 2 :icons: font :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnums: :sectnumlevels: 6 :partnums: :chapter-signifier: Chapter :part-signifier: Part :source-highlighter: rouge :experimental: :skip-front-matter: :book: true :pdf: false ifeval::["{backend}" == "html5"] :chapters-path: content/en/books/bookname/ endif::[] ifeval::["{backend}" == "pdf"] :chapters-path: endif::[] ifeval::["{backend}" == "epub3"] :chapters-path: endif::[] [abstract] Abstract Abstract section ''' toc::[] :sectnums!: \include::{chapters-path}preface/_index.adoc[leveloffset=+1] :sectnums: \include::{chapters-path}parti.adoc[lines=7..18] \include::{chapters-path}chapter-name/_index.adoc[leveloffset=+1] .... ==== [[examples-asciidoctor-article]] -== AsciiDoctor `article` +== AsciiDoctor *article* -.AsciiDoctor `article` +.AsciiDoctor *article* [example] ==== [.programlisting] .... --- title: An Example Article authors: - author: Your name and surname email: foo@example.com trademarks: ["general"] --- -\= An Example Article += An Example Article :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: ''' toc::[] -\== My First Section +== My First Section This is the first section in my article. -\== My First Sub-Section +== My First Sub-Section This is the first sub-section in my article. .... ==== diff --git a/documentation/content/en/books/fdp-primer/overview/_index.adoc b/documentation/content/en/books/fdp-primer/overview/_index.adoc index e14f0f5453..1daec39462 100644 --- a/documentation/content/en/books/fdp-primer/overview/_index.adoc +++ b/documentation/content/en/books/fdp-primer/overview/_index.adoc @@ -1,139 +1,139 @@ --- title: Chapter 1. Overview prev: books/fdp-primer/preface next: books/fdp-primer/tools description: Overview about the FreeBSD Documentation Process tags: ["overview", "FreeBSD Documentation Project", "quick start"] showBookMenu: true weight: 2 path: "/books/fdp-primer/" --- [[overview]] = Overview :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 1 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] Welcome to the FreeBSD Documentation Project (FDP). Quality documentation is crucial to the success of FreeBSD, and we value your contributions very highly. This document describes how the FDP is organized, how to write and submit documentation, and how to effectively use the available tools. Everyone is welcome to contribute to the FDP. Willingness to contribute is the only membership requirement. This primer shows how to: * Identify which parts of FreeBSD are maintained by the FDP. * Install the required documentation tools and files. * Make changes to the documentation. * Submit changes back for review and inclusion in the FreeBSD documentation. [[overview-quick-start]] == Quick Start Some preparatory steps must be taken before editing the FreeBSD documentation. First, subscribe to the {freebsd-doc}. Some team members also interact on the `#bsddocs` IRC channel on http://www.efnet.org/[EFnet]. These people can help with questions or problems involving the documentation. [.procedure] ==== . Install these packages. The `docproj` _meta-port_ installs all the applications required to do useful work with the FreeBSD documentation. + [source,shell] .... -# pkg install docproj python3 +# pkg install docproj .... + . Install a local working copy of the documentation from the FreeBSD repository in [.filename]#~/doc# (see crossref:working-copy[working-copy,The Working Copy]). + [source,shell] .... % git clone https://git.FreeBSD.org/doc.git ~/doc .... + . Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input. + Review the output and edit the file to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved. + . *_Always_* build and test the changes before submitting them. Running `make` in the top-level directory of the documentation will generate that documentation in HTML format. + [source,shell] .... % make .... + . When changes are complete and tested, generate a "diff file": + [source,shell] .... % cd ~/doc % git diff > bsdinstall.diff.txt .... + Give the diff file a descriptive name. In the example above, changes have been made to the [.filename]#bsdinstall# portion of the Handbook. . Submit the diff file using the web-based https://bugs.FreeBSD.org/bugzilla/enter_bug.cgi?product=Documentation[Problem Report] system. If using the web form, enter a Summary of _[patch] short description of problem_. Select the Component `Documentation`. In the Description field, enter a short description of the changes and any important details about them. Use the btn:[Add an attachment] button to attach the diff file. Finally, use the btn:[Submit Bug] button to submit your diff to the problem report system. ==== [[overview-doc]] == The FreeBSD Documentation Set The FDP is responsible for four categories of FreeBSD documentation. * _Handbook_: The Handbook is the comprehensive online resource and reference for FreeBSD users. * _FAQ_: The FAQ uses a short question and answer format to address questions that are frequently asked on the various mailing lists and forums devoted to FreeBSD. This format does not permit long and comprehensive answers. * _Manual pages_: The English language system manual pages are usually not written by the FDP, as they are part of the base system. However, the FDP can reword parts of existing manual pages to make them clearer or to correct inaccuracies. * _Web site_: This is the main FreeBSD presence on the web, visible at https://www.freebsd.org/[https://www.FreeBSD.org/] and many mirrors around the world. The web site is typically a new user's first exposure to FreeBSD. Translation teams are responsible for translating the Handbook and web site into different languages. Manual pages are not translated at present. Documentation source for the FreeBSD web site, Handbook, and FAQ is available in the documentation repository at `https://cgit.freebsd.org/doc/`. Source for manual pages is available in a separate source repository located at `https://cgit.freebsd.org/src/`. Documentation commit messages are visible with `git log`. Commit messages are also archived at link:{git-doc-all}. Web frontends to both of these repositories are available at https://cgit.freebsd.org/doc/[] and https://cgit.freebsd.org/src/[]. Many people have written tutorials or how-to articles about FreeBSD. Some are stored as part of the FDP files. In other cases, the author has decided to keep the documentation separate. The FDP endeavors to provide links to as much of this external documentation as possible. diff --git a/documentation/content/en/books/fdp-primer/po-translations/_index.adoc b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc index 8a9cceed89..5c688ab1c2 100644 --- a/documentation/content/en/books/fdp-primer/po-translations/_index.adoc +++ b/documentation/content/en/books/fdp-primer/po-translations/_index.adoc @@ -1,441 +1,441 @@ --- title: Chapter 9. PO Translations prev: books/fdp-primer/translations next: books/fdp-primer/manual-pages description: How to work with PO translation in the FreeBSD Documentation Project tags: ["po", "translations", "tutorial", "quick start"] showBookMenu: true weight: 10 path: "/books/fdp-primer/" --- [[po-translations]] = PO Translations :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 9 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] [[po-translations-introduction]] == Introduction The http://www.gnu.org/software/gettext/[GNU gettext] system offers translators an easy way to create and maintain translations of documents. Translatable strings are extracted from the original document into a PO (Portable Object) file. Translated versions of the strings are entered with a separate editor. The strings can be used directly or built into a complete translated version of the original document. [[po-translations-quick-start]] == Quick Start The procedure shown in crossref:overview[overview-quick-start,Quick Start] is assumed to have already been performed. The `TRANSLATOR` option is required and already enabled by default in the package:textproc/docproj[] port. This example shows the creation of a Spanish translation of the short extref:{leap-seconds}[Leap Seconds] article. [[po-translations-quick-start-install-po-editor]] [.procedure] ==== .Procedure: Install a PO Editor . A PO editor is needed to edit translation files. This example uses package:editors/poedit[]. + [source,shell] .... # pkg install poedit .... ==== [[po-translations-quick-start-initial-setup]] [.procedure] ==== .Procedure: Initial Setup When a new translation is first created, the directory structure must be created or copied from the English original: . Create a directory for the new translation. The English article source is in [.filename]#~/doc/documentation/content/en/articles/leap-seconds/#. The Spanish translation will go in [.filename]#~/doc/documentation/content/es/articles/leap-seconds/#. The path is the same except for the name of the language directory. The English article source is in [.filename]#~/doc/en/articles/leap-seconds/#. The Spanish translation will go in [.filename]#~/doc/es/articles/leap-seconds/#. The path is the same except for the name of the language directory. + [source,shell] .... % mkdir ~/doc/documentation/content/es/articles/leap-seconds .... . Copy the [.filename]#_index.adoc# from the original document into the translation directory: + [source,shell] .... % cp ~/doc/documentation/content/en/articles/leap-seconds/_index.adoc \ ~/doc/documentation/content/es/articles/leap-seconds/ .... ==== [[po-translations-quick-start-translation]] [.procedure] ==== .Procedure: Translation Translating a document consists of two steps: extracting translatable strings from the original document, and entering translations for those strings. These steps are repeated until the translator feels that enough of the document has been translated to produce a usable translated document. . Extract the translatable strings from the original English version into a PO file: + [source,shell] .... % cd ~/doc % po4a-gettextize \ --format asciidoc \ --option compat=asciidoctor \ --option yfm_keys=title,part,description \ --master "documentation/content/en/articles/leap-seconds/_index.adoc" \ --master-charset "UTF-8" \ --copyright-holder "The FreeBSD Project" \ --package-name "FreeBSD Documentation" \ --po "documentation/content/es/articles/leap-seconds/_index.po" .... + . Use a PO editor to enter translations in the PO file. There are several different editors available. [.filename]#poedit# from package:editors/poedit[] is shown here. + [source,shell] .... % poedit documentation/content/es/articles/leap-seconds/_index.po .... ==== [[po-translations-quick-generating-a-translated-document]] [.procedure] ==== .Procedure: Generating a Translated Document . Generate the translated document: + [source,shell] .... % cd ~/doc % po4a-translate \ --format asciidoc \ --option compat=asciidoctor \ --option yfm_keys=title,part,description \ --master "documentation/content/en/articles/leap-seconds/_index.adoc" \ --master-charset "UTF-8" \ --po "documentation/content/es/articles/leap-seconds/_index.po" \ --localized "documentation/content/es/articles/leap-seconds/_index.adoc" \ --localized-charset "UTF-8" \ --keep 0 .... + The name of the generated document matches the name of the English original, usually [.filename]#_index.adoc#. + . Check the generated file by rendering it to HTML and viewing it with a web browser: + [source,shell] .... % cd ~/doc/documentation % make .... ==== [[po-translations-creating]] == Creating New Translations The first step to creating a new translated document is locating or creating a directory to hold it. FreeBSD puts translated documents in a subdirectory named for their language and region in the format [.filename]#lang#. _lang_ is a two-character lowercase code. [[po-translations-language-names]] .Language Names [cols="1,1,1", frame="none", options="header"] |=== | Language | Region | Translated Directory Name |English |United States |[.filename]#en# |Bengali |Bangladesh |[.filename]#bn# |Danish |Denmark |[.filename]#da# |German |Germany |[.filename]#de# |Greek |Greece |[.filename]#el# |Spanish |Spain |[.filename]#es# |French |France |[.filename]#fr# |Hungarian |Hungary |[.filename]#hu# |Italian |Italy |[.filename]#it# |Japanese |Japan |[.filename]#ja# |Korean |Korea |[.filename]#ko# |Mongolian |Mongolia |[.filename]#mn# |Dutch |Netherlands |[.filename]#nl# |Polish |Poland |[.filename]#pl# |Portuguese |Brazil |[.filename]#pt-br# |Russian |Russia |[.filename]#ru# |Turkish |Turkey |[.filename]#tr# |Chinese |China |[.filename]#zh-cn# |Chinese |Taiwan |[.filename]#zh-tw# |=== The translations are in subdirectories of the main documentation directory, -here assumed to be [.filename]#~/doc/documentation/# as shown in <>. +here assumed to be [.filename]#~/doc/documentation/# as shown in crossref:overview[overview-quick-start, Quick Start]. For example, German translations are located in [.filename]#~/doc/documentation/content/de/#, and French translations are in [.filename]#~/doc/documentation/content/fr/#. Each language directory contains separate subdirectories named for the type of documents, usually [.filename]#articles/# and [.filename]#books/#. Combining these directory names gives the complete path to an article or book. For example, the French translation of the NanoBSD article is in [.filename]#~/doc/documentation/content/fr/articles/nanobsd/#, and the Mongolian translation of the Handbook is in [.filename]#~/doc/documentation/content/mn/books/handbook/#. A new language directory must be created when translating a document to a new language. If the language directory already exists, only a subdirectory in the [.filename]#articles/# or [.filename]#books/# directory is needed. [[po-translations-creating-example]] .Creating a Spanish Translation of the Porter's Handbook [example] ==== Create a new Spanish translation of the extref:{porters-handbook}[Porter's Handbook]. The original is a book in [.filename]#~/doc/documentation/content/en/books/porters-handbook/#. [.procedure] ====== . The Spanish language books directory [.filename]#~/doc/documentation/content/es/books/# already exists, so only a new subdirectory for the Porter's Handbook is needed: + [source,shell] .... % cd ~/doc/documentation/content/es/books % mkdir porters-handbook .... . Copy the content from the original book: + [source,shell] .... % cd porters-handbook % cp -R ~/doc/documentation/content/en/books/porters-handbook/* . .... + Now the document structure is ready for the translator to begin translating with `po4a` command. ====== ==== [[po-translations-translating]] == Translating The gettext system greatly reduces the number of things that must be tracked by a translator. Strings to be translated are extracted from the original document into a PO file. Then a PO editor is used to enter the translated versions of each string. The FreeBSD PO translation system does not overwrite PO files, so the extraction step can be run at any time to update the PO file. A PO editor is used to edit the file. package:editors/poedit[] is shown in these examples because it is simple and has minimal requirements. Other PO editors offer features to make the job of translating easier. The Ports Collection offers several of these editors, including package:devel/gtranslator[]. It is important to preserve the PO file. It contains all of the work that translators have done. [[po-translations-translating-example]] .Translating the Porter's Handbook to Spanish [example] ==== [.procedure] ====== . Change to the base directory and update all PO files. + [source,shell] .... % cd ~/doc % po4a-gettextize \ --format asciidoc \ --option compat=asciidoctor \ --option yfm_keys=title,part,description \ --master "documentation/content/en/books/porters-handbook/_index.adoc" \ --master-charset "UTF-8" \ --copyright-holder "The FreeBSD Project" \ --package-name "FreeBSD Documentation" \ --po "documentation/content/es/books/porters-handbook/_index.po" .... . Enter translations using a PO editor: + [source,shell] .... % poedit documentation/content/es/books/porters-handbook/_index.po .... ====== These steps are necessary for all `.adoc` files, excluding `chapters-order.adoc` and `toc-*.adoc`. ==== [[po-translations-tips]] == Tips for Translators [[po-translations-tips-xmltags]] === Preserving AsciiDoc macros Preserve AsciiDoc macros that are shown in the English original. .Preserving AsciiDoc macros [example] ==== English original: [.programlisting] .... msgid "" "This example shows the creation of a Spanish translation of the short " "extref:{leap-seconds}[Leap Seconds] article." .... Spanish translation: [.programlisting] .... msgid "" "Este ejemplo muestra la creación de un artículo con poco contenido como el artículo " "extref:{leap-seconds}[Leap Seconds]." .... ==== [[po-translations-tips-spaces]] === Preserving Spaces Preserve existing spaces at the beginning and end of strings to be translated. The translated version must have these spaces also. [[po-translations-tips-verbatim]] === Verbatim Tags The contents of some tags should be copied verbatim, not translated: * `man:man[1]` * `package:package[]` * `link` * `image` * `include` * `Admonitions` * `id's` * `Heading tags` * `source` [[po-translations-building]] == Building a Translated Document A translated version of the original document can be created at any time. Any untranslated portions of the original will be included in English in the resulting document. Most PO editors have an indicator that shows how much of the translation has been completed. This makes it easy for the translator to see when enough strings have been translated to make building the final document worthwhile. [[po-translations-submitting]] == Submitting the New Translation Prepare the new translation files for submission. This includes adding the files to the version control system, setting additional properties on them, then creating a diff for submission. The diff files created by these examples can be attached to a https://bugs.freebsd.org/bugzilla/enter_bug.cgi?product=Documentation[documentation bug report] or https://reviews.freebsd.org/[code review]. [[po-translations-submitting-spanish]] .Spanish Translation of the NanoBSD Article [example] ==== [.procedure] ====== . Create a diff of the new files from the [.filename]#~/doc/# base directory so the full path is shown with the filenames. This helps committers identify the target language directory. + [source,shell] .... % cd ~/doc % git diff documentation/content/es/articles/nanobsd/ > /tmp/es_nanobsd.diff .... ====== ==== diff --git a/documentation/content/en/books/fdp-primer/see-also/_index.adoc b/documentation/content/en/books/fdp-primer/see-also/_index.adoc index 84dc15aa28..f41b9b6270 100644 --- a/documentation/content/en/books/fdp-primer/see-also/_index.adoc +++ b/documentation/content/en/books/fdp-primer/see-also/_index.adoc @@ -1,69 +1,77 @@ --- title: Chapter 13. See Also prev: books/fdp-primer/editor-config/ next: books/fdp-primer/examples description: More information about the FreeBSD Documentation Project tags: ["additional information", "AsciiDoctor", "HTML"] showBookMenu: true weight: 14 path: "/books/fdp-primer/" --- [[see-also]] = See Also :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 13 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] This document is deliberately not an exhaustive discussion of AsciiDoc and the FreeBSD Documentation Project. For more information about these, you are encouraged to see the following web sites. [[see-also-fdp]] == The FreeBSD Documentation Project * link:https://www.FreeBSD.org/docproj/[The FreeBSD Documentation Project web pages] * extref:{handbook}[The FreeBSD Handbook] +[[see-also-hugo]] +== Hugo + +* link:https://gohugo.io/[Hugo] +* link:https://gohugo.io/documentation/[Hugo documentation] + [[see-also-asciidoc]] == AsciiDoctor * link:https://asciidoctor.org/[AsciiDoctor] +* link:https://docs.asciidoctor.org/[AsciiDoctor Documentation Portal] [[see-also-html]] == HTML * link:http://www.w3.org/[The World Wide Web Consortium] * link:https://dev.w3.org/html5/spec-LC/[The HTML 5 specification] * link:https://www.w3.org/Style/CSS/specs.en.html[CSS specification] +* link:https://sass-lang.com/[Sass] diff --git a/documentation/content/en/books/fdp-primer/structure/_index.adoc b/documentation/content/en/books/fdp-primer/structure/_index.adoc index b825e1cd28..8daaeda713 100644 --- a/documentation/content/en/books/fdp-primer/structure/_index.adoc +++ b/documentation/content/en/books/fdp-primer/structure/_index.adoc @@ -1,271 +1,252 @@ --- title: Chapter 4. Documentation Directory Structure prev: books/fdp-primer/working-copy next: books/fdp-primer/doc-build description: Documentation Directory Structure explanation used in the FreeBSD Documentation Project tags: ["directory structure", "organization"] showBookMenu: true weight: 5 path: "/books/fdp-primer/" --- [[structure]] = Documentation Directory Structure :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 4 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] endif::[] -Files and directories in the [.filename]#doc/# tree follow a structure meant to: +Files and directories in the *doc/* tree follow a structure meant to: . Make it easy to automate converting the document to other formats. . Promote consistency between the different documentation organizations, to make it easier to switch between working on different documents. . Make it easy to decide where in the tree new documentation should be placed. In addition, the documentation tree must accommodate documents in many different languages. It is important that the documentation tree structure does not enforce any particular defaults or cultural preferences. [[structure-top]] == The Top Level, doc/ -There are three sections under [.filename]#doc/#, documentation and website share the same structure. +There are three sections under *doc/*, documentation and website share the same structure. [cols="20%,80%", frame="none", options="header"] |=== | Directory | Usage -|[.filename]#documentation# -|Contains all the articles and books in AsciiDoc format. +| *documentation* +| Contains all the articles and books in AsciiDoc format. Contains subdirectories to further categorize the information by languages. -|[.filename]#shared# -|Contains files that are not specific to the various translations of the documentation. +| *tools* +| Contains a set of tools used to translate the documentation and the website using link:https://weblate.org/en/[weblate]. +The weblate instance can be found link:https://translate-dev.freebsd.org[here] + +| *shared* +| Contains files that are not specific to the various translations of the documentation. Contains subdirectories to further categorize the information by languages and three files to store the authors, releases and mirrors information. This directory is shared between `documentation` and the `website`. -|[.filename]#website# -|Contains the link:https://www.FreeBSD.org[FreeBSD website] in AsciiDoc format. +| *website* +| Contains the link:https://www.FreeBSD.org[FreeBSD website] in AsciiDoc format. Contains subdirectories to further categorize the information by languages. |=== [[structure-locale]] == The Directories These directories contain the documentation and the website. The documentation is organized into subdirectories below this level, following the link:https://gohugo.io/getting-started/directory-structure/[Hugo directory structure]. [cols="20%,80%", frame="none", options="header"] |=== | Directory | Usage -|[.filename]#archetypes# -|Contain templates to create new articles, books and webpages. +| *archetypes* +| Contain templates to create new articles, books and webpages. For more information take a look link:https://gohugo.io/content-management/archetypes/[here]. -|[.filename]#config# -|Contain the Hugo configuration files. +| *config* +| Contain the Hugo configuration files. One main file and one file per language. For more information take a look link:https://gohugo.io/getting-started/configuration/[here]. -|[.filename]#content# -|Contain the books, articles and webpages. +| *content* +| Contain the books, articles and webpages. One directory exists for each available translation of the documentation, for example `en` and `zh-tw`. -| [.filename]#data# +| *data* | Contain custom data for build the website in link:https://en.wikipedia.org/wiki/TOML[TOML] format. This directory is used to store the events, news, press, etc. For more information take a look link:https://gohugo.io/templates/data-templates/[here]. -| [.filename]#static# +| *static* | Contain static assets. Images, security advisories, the pgpkeys, etc. For more information take a look link:https://gohugo.io/content-management/static-files/[here]. -| [.filename]#themes# +| *themes* | Contain the templates in the form of `.html` files that specify how the website looks. For more information take a look link:https://gohugo.io/templates/[here]. -| [.filename]#tools# +| *tools* | Contain tools used to enhance the documentation build. For example to generate the Table of Contents of the books, etc. -| [.filename]#beastie.png# +| *beastie.png* | This image doesn't need an introduction ;) -| [.filename]#LICENSE# +| *LICENSE* | License of the documentation, shared and website. BSD 2-Clause License. -| [.filename]#Makefile# -| The [.filename]#Makefile# defines the build process of the documentation and the website. +| *Makefile* +| The *Makefile* defines the build process of the documentation and the website. |=== [[structure-document]] == Document-Specific Information This section contains specific notes about particular documents managed by the FDP. [[structure-document-books]] == The Books: books/ The books are written in AsciiDoc. The books are organized as an AsciiDoc `book`. The books are divided into ``part``s, each of which contains several ``chapter``s. ``chapter``s are further subdivided into sections (`=`) and subsections (`==`, `===`) and so on. [[structure-document-books-physical]] === Physical Organization There are a number of files and directories within the books directory, all with the same structure. [[structure-document-books-physical-index]] ==== _index.adoc -The [.filename]#_index.adoc# defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables and the abstract section. +The *_index.adoc* defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables and the abstract section. [[structure-document-books-physical-book]] ==== book.adoc -The [.filename]#_index.adoc# defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables, the abstract section and all the chapters. +The *_index.adoc* defines some AsciiDoc variables that affect how the AsciiDoc source is converted to other formats and list the Table of Contents, Table of Examples, Table of Figures, Table of Tables, the abstract section and all the chapters. This file is used to generate the PDF with `asciidoctor-pdf` and to generate the book in one `html` page. [[structure-document-books-physical-part]] ==== part*.adoc -The [.filename]#part*.adoc# files stores a brief introduction of one part of the book. - -[[structure-document-books-physical-toc]] -==== toc*.adoc -The [.filename]#toc*.adoc# files stores the Table of Contents, Table of Figures, Table of Examples, Table of Tables and different Table of Contents for each part. -All of these files are generated by the Python `tools`. -*Please don't edit them.* - -[[structure-document-books-physical-chapters-order]] -==== chapters-order.adoc -The [.filename]#chapters-order.adoc# file stores the order of the book chapters. - -[IMPORTANT] -==== -Please be careful with this file. -It is used by the Python `tools` to generate the Table of Contents of the books. -In case of editing this file, first contact the mailto:doceng@freebsd.org[Documentation Engineering] team. -==== +The *part*.adoc* files stores a brief introduction of one part of the book. [[structure-document-handbook-physical-chapters]] ==== directory/_index.adoc -Each chapter in the Handbook is stored in a file called [.filename]#_index.adoc# in a separate directory from the other chapters. +Each chapter in the Handbook is stored in a file called *_index.adoc* in a separate directory from the other chapters. For example, this is an example of the header of one chapter: [.programlisting] .... --- title: Chapter 8. Configuring the FreeBSD Kernel part: Part II. Common Tasks prev: books/handbook/multimedia next: books/handbook/printing --- [[kernelconfig]] -\= Configuring the FreeBSD Kernel <.> += Configuring the FreeBSD Kernel ... .... -<.> The character at the end of the line should not be used in a production document. -This character is here to skip this title in the autogenerated [.filename]#toc-*.adoc# files. +When the HTML5 version of the Handbook is produced, this will yield *kernelconfig/index.html*. -When the HTML5 version of the Handbook is produced, this will yield [.filename]#kernelconfig/index.html#. - -A brief look will show that there are many directories with individual [.filename]#_index.adoc# files, including [.filename]#basics/_index.adoc#, [.filename]#introduction/_index.adoc#, and [.filename]#printing/_index.xml#. +A brief look will show that there are many directories with individual *_index.adoc* files, including *basics/_index.adoc*, *introduction/_index.adoc*, and *printing/_index.adoc*. [IMPORTANT] ==== Do not name chapters or directories after their ordering within the Handbook. This ordering can change as the content within the Handbook is reorganized. Reorganization should be possible without renaming files, unless entire chapters are being promoted or demoted within the hierarchy. ==== [[structure-document-articles]] == The Articles: articles/ The articles are written in AsciiDoc. The articles are organized as an AsciiDoc `article`. The articles are divided into sections (`=`) and subsections (`==`, `===`) and so on. [[structure-document-articles-physical]] === Physical Organization -There is one [.filename]#_index.adoc# file per article. +There is one *_index.adoc* file per article. [[structure-document-articles-physical-index]] ==== _index.adoc -The [.filename]#_index.adoc# file contains all the AsciiDoc variables and the content. +The *_index.adoc* file contains all the AsciiDoc variables and the content. For example, this is an example of one article, the structure is pretty similar to one book chapter: [.programlisting] .... --- title: Why you should use a BSD style license for your Open Source Project authors: - author: Bruce Montague email: brucem@alumni.cse.ucsc.edu trademarks: ["freebsd", "intel", "general"] --- -\= Why you should use a BSD style license for your Open Source Project <1> += Why you should use a BSD style license for your Open Source Project :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: ''' toc::[] [[intro]] -\== Introduction <1> +== Introduction .... - -<1> The character at the end of the line should not be used in a production document. -This character is here to skip this title in the autogenerated [.filename]#toc-*.adoc# files.