Skip to content

Latest commit

 

History

History
192 lines (118 loc) · 6.9 KB

extended-include-macro.adoc

File metadata and controls

192 lines (118 loc) · 6.9 KB

Extended Include Macro

Asciidoctor already provides an include macro which can still be used as usual. However, if the include macro starts with specific variables after the double colon, a special handling of the include macro is activated. For example, files can be included using the variable {find} as in include::{find}myFile[]. Despite having some special handling when using specific variables, the usual behaviour of the built-in include is still preserved and all its attributes can still be used. The following documentation focuses on the include macro with activated special handling.

{find} Include Macro

The general idea of the {find} variable in an include macro is to search the given file and replace the variable with the path to the matched file. The search looks for the given file in the current directory and every parent directory. To stop the search at a specific parent root directory, the command line attribute findroot can be used: -a findroot=docrootdir. In short, it behaves the same like the {find} variable (see: Special Variables), but enables two additional attributes which can be given in the squared brackets of the include macro.

Usage:

include::{find}Target[Attributes]

With:

  • Target (required): The name of the file whose contents shall be included. The file name can contain directories. The extension .adoc can be omitted.

  • Attributes (optional):

    • FILE_ONCE: Includes the same file only once.

    • TARGET_ONCE (alias ONCE): Includes the same target only once.

    • (all other include attributes such as 'lines')

Warnings and Errors:

  • Error: File Not Found Is issued in case the given target could not be found.

  • Error: Circular Dependency Is issued in case the included files depend on each other. The last file which would create a circular dependency cycle is omitted. This error is only issued if all include macros of the cycle use the {find} macro.

  • Warning: Cannot Detect Circular Dependencies Is issued in case one or more includes do not use the {find} macro. Despite this issue, circular dependencies can still be found if all of the causing files are included using the {find} macro.

  • Warning: Multiple File Matches Is issued in case the given target is found at multiple locations. The first match is chosen to be included.

  • Warning: Inconsistent Use of Attributes Is issued in case one of the attributes is used inconsistently. The TARGET_ONCE attribute is supposed to be used at none or at all includes with the same target. The FILE_ONCE attribute is supposed to be used at none or at all includes matching the same file.

Example:

The following line includes the file file.adoc in the subdir dir. The location of that file is found by the {find} directive (see: Special Variables). The attribute ONCE is the shorthand form for TARGET_ONCE.

include::{find}dir/file.adoc[ONCE]

{api} Include Macro

The general idea of the {api} variable in an include macro is to include the generated API adoc text (of stdLib) which previously was generated by the exporter wizard. To specify the included API documentation, a PQN (see PQN) is used.

Usage:

include::{api}PQN[Attributes]

With:

  • PQN (required): The PQN of the source element whose generated API shall be included.

  • Attributes (optional):

    • leveloffset: Sets the leveloffset of the included sections. (see: Asciidoctor)

    • lines: Selects the set of lines that will be included. (see: Asciidoctor)

Requires:

  • Asciidoctor variable gen_adoc_dir

Warnings and Errors:

  • Error: Missing Config Variable 'gen_adoc_dir' Is issued in case the variable gen_adoc_dir is not found.

  • Error: PQN Could Not Be Parsed Is issued in case the given PQN is invalid.

  • Error: PQN Is Ambiguous Is issued in case the given PQN is ambiguous.

  • Error: PQN Not Found Is issued in case no API element could be found in the index for the given PQN.

  • Error: Could Not Parse Attributes Is issued in case the given attributes could not be parsed.

  • Error: Could Not Read Module File Is issued in case the module file could not be read. Note that the given PQN could be read. This error might occur when the API was not generated before.

Example:

The following line includes the API of the constructor of the class Sequence in the module named Sequence. The generatd API of that source element is found by the {api} directive. The attribute leveloffset adds an offset to the included API sections.

include::{api}++stdlib_api:packages:eu.numberfour.n4js.base.api-tests:src/n4js/n4/lang/Sequence:Sequence#constructor++[leveloffset=+2]

{req} Include Macro

The general idea of the {req} variable in an include macro is to include generated requirement sections (of stdLib) which previously were generated by the exporter wizard. To specify the included requirement section, the requirement id (e.g. IDE-2448) is used.

Usage:

include::{req}REQID[Attributes]

With:

  • REQID (required): The requirement ID of the requirement whose generated section shall be included.

  • Attributes (optional):

    • leveloffset: Sets the leveloffset of the included sections. (see: Asciidoctor)

    • lines: Selects the set of lines that will be included. (see: Asciidoctor)

Requires:

  • Asciidoctor variable gen_adoc_dir

Warnings and Errors:

  • Error: Missing Config Variable 'gen_adoc_dir' Is issued in case the variable gen_adoc_dir is not found.

  • Error: Could Not Resolve Requirement File Is issued in case the given requirement ID could be resolved against the directory path of the generated adoc files.

  • Error: Could Not Parse Attributes Is issued in case the given attributes could not be parsed.

  • Error: Could Not Read Requirement File Is issued in case the requirement file could not be read. Note that the given requirement ID could be read. This error might occur when the requirement section was not generated before.

Example:

The following line includes the API of the constructor of the class Sequence in the module named Sequence. The generatd API of that source element is found by the {api} directive. The attribute leveloffset adds an offset to the included API sections.

include::{api}++stdlib_api:packages:eu.numberfour.n4js.base.api-tests:src/n4js/n4/lang/Sequence:Sequence#constructor++[leveloffset=+2]

{src} Include Macro

Includes source code (of StdLib API) from GitHub. Uses a PQN to reference the source element (e.g. a method) which is to be included. (tbd)