adding-packages-asciidoc.txt 4.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122
  1. // -*- mode:doc; -*-
  2. // vim: syntax=asciidoc
  3. === Infrastructure for asciidoc documents
  4. [[asciidoc-documents-tutorial]]
  5. The Buildroot manual, which you are currently reading, is entirely written
  6. using the http://asciidoc.org/[AsciiDoc] mark-up syntax. The manual is then
  7. rendered to many formats:
  8. * html
  9. * split-html
  10. * pdf
  11. * epub
  12. * text
  13. Although Buildroot only contains one document written in AsciiDoc, there
  14. is, as for packages, an infrastructure for rendering documents using the
  15. AsciiDoc syntax.
  16. Also as for packages, the AsciiDoc infrastructure is available from a
  17. xref:outside-br-custom[br2-external tree]. This allows documentation for
  18. a br2-external tree to match the Buildroot documentation, as it will be
  19. rendered to the same formats and use the same layout and theme.
  20. ==== +asciidoc-document+ tutorial
  21. Whereas package infrastructures are suffixed with +-package+, the document
  22. infrastructures are suffixed with +-document+. So, the AsciiDoc infrastructure
  23. is named +asciidoc-document+.
  24. Here is an example to render a simple AsciiDoc document.
  25. ----
  26. 01: ################################################################################
  27. 02: #
  28. 03: # foo-document
  29. 04: #
  30. 05: ################################################################################
  31. 06:
  32. 07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
  33. 08: $(eval $(call asciidoc-document))
  34. ----
  35. On line 7, the Makefile declares what the sources of the document are.
  36. Currently, it is expected that the document's sources are only local;
  37. Buildroot will not attempt to download anything to render a document.
  38. Thus, you must indicate where the sources are. Usually, the string
  39. above is sufficient for a document with no sub-directory structure.
  40. On line 8, we call the +asciidoc-document+ function, which generates all
  41. the Makefile code necessary to render the document.
  42. ==== +asciidoc-document+ reference
  43. The list of variables that can be set in a +.mk+ file to give metadata
  44. information is (assuming the document name is +foo+) :
  45. * +FOO_SOURCES+, mandatory, defines the source files for the document.
  46. * +FOO_RESOURCES+, optional, may contain a space-separated list of paths
  47. to one or more directories containing so-called resources (like CSS or
  48. images). By default, empty.
  49. * +FOO_DEPENDENCIES+, optional, the list of packages (most probably,
  50. host-packages) that must be built before building this document.
  51. There are also additional hooks (see xref:hooks[] for general information
  52. on hooks), that a document may set to define extra actions to be done at
  53. various steps:
  54. * +FOO_POST_RSYNC_HOOKS+ to run additional commands after the sources
  55. have been copied by Buildroot. This can for example be used to
  56. generate part of the manual with information extracted from the
  57. tree. As an example, Buildroot uses this hook to generate the tables
  58. in the appendices.
  59. * +FOO_CHECK_DEPENDENCIES_HOOKS+ to run additional tests on required
  60. components to generate the document. In AsciiDoc, it is possible to
  61. call filters, that is, programs that will parse an AsciiDoc block and
  62. render it appropriately (e.g. http://ditaa.sourceforge.net/[ditaa] or
  63. https://pythonhosted.org/aafigure/[aafigure]).
  64. * +FOO_CHECK_DEPENDENCIES_<FMT>_HOOKS+, to run additional tests for
  65. the specified format +<FMT>+ (see the list of rendered formats, above).
  66. Here is a complete example that uses all variables and all hooks:
  67. ----
  68. 01: ################################################################################
  69. 02: #
  70. 03: # foo-document
  71. 04: #
  72. 05: ################################################################################
  73. 06:
  74. 07: FOO_SOURCES = $(sort $(wildcard $(pkgdir)/*))
  75. 08: FOO_RESOURCES = $(sort $(wildcard $(pkgdir)/ressources))
  76. 09:
  77. 10: define FOO_GEN_EXTRA_DOC
  78. 11: /path/to/generate-script --outdir=$(@D)
  79. 12: endef
  80. 13: FOO_POST_RSYNC_HOOKS += FOO_GEN_EXTRA_DOC
  81. 14:
  82. 15: define FOO_CHECK_MY_PROG
  83. 16: if ! which my-prog >/dev/null 2>&1; then \
  84. 17: echo "You need my-prog to generate the foo document"; \
  85. 18: exit 1; \
  86. 19: fi
  87. 20: endef
  88. 21: FOO_CHECK_DEPENDENCIES_HOOKS += FOO_CHECK_MY_PROG
  89. 22:
  90. 23: define FOO_CHECK_MY_OTHER_PROG
  91. 24: if ! which my-other-prog >/dev/null 2>&1; then \
  92. 25: echo "You need my-other-prog to generate the foo document as PDF"; \
  93. 26: exit 1; \
  94. 27: fi
  95. 28: endef
  96. 29: FOO_CHECK_DEPENDENCIES_PDF_HOOKS += FOO_CHECK_MY_OTHER_PROG
  97. 30:
  98. 31: $(eval $(call asciidoc-document))
  99. ----