[Bug 266881] AsciiDoctor Primer: include more about macros

From: <bugzilla-noreply_at_freebsd.org>
Date: Fri, 07 Oct 2022 07:03:07 UTC 
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=266881

            Bug ID: 266881
           Summary: AsciiDoctor Primer: include more about macros
           Product: Documentation
           Version: Latest
          Hardware: Any
               URL: https://github.com/freebsd/freebsd-doc/blob/main/docum
                    entation/content/en/books/fdp-primer/asciidoctor-prime
                    r/_index.adoc
                OS: Any
            Status: New
          Severity: Affects Some People
          Priority: ---
         Component: Books & Articles
          Assignee: doc@FreeBSD.org
          Reporter: grahamperrin@freebsd.org

Can the primer gain a list of available macros? 

Also, for each one: 

* context (not too complex)

* at least one example. 

Thanks


Background
==========

<https://docs.freebsd.org/en/books/fdp-primer/asciidoctor-primer/#asciidoctor-links>
comprises two subsections: 

* External links
* Internal link

– no hint of how to form the special link to a page for a port. 

For discovery, for an example, I browsed source code for part of the FreeBSD
Handbook. 

Then, thanks to Pau Amma, I found my way to this: 

<https://github.com/freebsd/freebsd-doc/blob/main/shared/lib/PackagesMacro/extension.rb>

– for PackagesMacro, which, if I understand correctly, relates to 
  the macro named: 

    package

Example use: 

    package:ports-mgmt/pkg[]

– current result (cgit): 

    <https://cgit.freebsd.org/ports/tree/ports-mgmt/pkg/pkg-descr>

– a three-word description.

-- 
You are receiving this mail because:
You are the assignee for the bug.