@cppalliance/antora-cpp-tagfiles-extension
v0.0.4
Published
C++ Tagfiles Extension for Antora
Downloads
799
Readme
cpp:std::vector[]
This will render as a link to the std::vector
class in the tagfile.
https://en.cppreference.com/w/cpp/container/vector[std::vector,window="_blank"]
Which renders as
https://en.cppreference.com/w/cpp/container/vector[std::vector,window="_blank"]
.
The extension supports fundamental types, custom tagfiles, using namespaces directives, template parameters, nested symbols, and replacing target names.
Configuration {#_configuration}
Unknown symbols
If the extension can't find a symbol in the tagfile, it will render the symbol as plain text.
cpp:unknown[]
This will render as plain text:
`unknown`
Which renders as unknown
.
Fundamental types
Fundamental types include links to cppreference:
cpp:int[]
This will render as a link to the int
fundamental type in
cppreference.
`https://en.cppreference.com/w/cpp/language/types#Standard_integer_types[int,window="_blank"]`
Which renders as
https://en.cppreference.com/w/cpp/language/types#Standard_integer_types[int,window="_blank"]
.
Symbols from Tagfiles
Symbols from tagfiles are rendered as links:
cpp:std::string[]
This will render as a link to the std::string
class in the
cppreference tagfile.
`https://en.cppreference.com/w/cpp/string/basic_string[std::string,window="_blank"]`
Which renders as
https://en.cppreference.com/w/cpp/string/basic_string[std::string,window="_blank"]
.
Template classes without parameters are also supported:
cpp:std::vector[]
This will render as a link to the std::vector
class in the
cppreference tagfile.
`https://en.cppreference.com/w/cpp/container/vector[std::vector,window="_blank"]`
Which renders as
https://en.cppreference.com/w/cpp/container/vector[std::vector,window="_blank"]
.
Symbols from custom tagfiles are rendered without the window="_blank"
attribute if the base_url
relative.
cpp:is_charset[]
This will render as a link to the boost::urls::grammar::is_charset
class in the boost-url-doxygen.tag.xml
tagfile.
`xref:reference:boost/urls/grammar/is_charset.adoc[boost::urls::grammar::is_charset]`
Components
When components define their own tagfiles, these tagfiles only affect the component where they are defined and they have precedence over tagfiles defined in the playbook.
cpp:boost::urls::string_token::assign_to[]
This will render as a link to the boost::urls::string_token::assign_to
class in the boost-url-doxygen.tag.xml
tagfile.
`xref:reference:boost/urls/string_token/assign_to.adoc[boost::urls::string_token::assign_to]`
However, if the some other component uses cpp:
for the same symbol
without the appropriate tagfile, the symbol will be rendered as plain
text.
`boost::urls::string_token::assign_to`
Namespaces
Default namespaces can also be defined in the playbook or in the
component. When there's no match for the full symbol, the extension will
try to find the symbol in the namespaces. Assuming
boost::urls::grammar
is defined in the playbook or the component:
cpp:boost::urls::grammar::is_charset[]
cpp:is_charset[]
This will render as a link to the boost::urls::grammar::is_charset
class in the boost-url-doxygen.tag.xml
tagfile. However, the link text
will be whatever was provided to the extension.
`xref:reference:boost/urls/grammar/is_charset.adoc[boost::urls::grammar::is_charset]`
`xref:reference:boost/urls/grammar/is_charset.adoc[is_charset]`
As with tagfiles, the namespaces defined in a component only affect that
component. The namespace std::
can also be defined:
cpp:std::string[]
cpp:string[]
This will render as a link to the std::string
class in the
cppreference tagfile.
`https://en.cppreference.com/w/cpp/string/basic_string[std::string,window="_blank"]`
`https://en.cppreference.com/w/cpp/string/basic_string[string,window="_blank"]`
Template parameters
Template parameters are supported. The extension will also include links from the tagfile for the template parameters.
cpp:std::vector<int>[]
This will render as a link to the std::vector<int>
class in the
cppreference tagfile.
`https://en.cppreference.com/w/cpp/container/vector[std::vector,window="_blank"]<https://en.cppreference.com/w/cpp/language/types#Standard_integer_types[int,window=_blank]>`
Which renders as
https://en.cppreference.com/w/cpp/container/vector[std::vector,window="_blank"]<https://en.cppreference.com/w/cpp/language/types#Standard_integer_types[int,window=_blank]>
.
Symbols from custom tagfiles can also be used with template parameters:
cpp:std::vector<url_view>[]
This will render as a link to the std::vector<url_view>
class in the
cppreference tagfile.
`https://en.cppreference.com/w/cpp/container/vector[std::vector,window=\"_blank\"]<url_view>`
Which renders as
https://en.cppreference.com/w/cpp/container/vector[std::vector,window="blank"]<url_view>
.
If the namespace boost::urls
is being used in the context, it will
also be used to resolve url_view
:
cpp:std::vector<url_view>[]
This will render as a link to the std::vector<url_view>
class in the
cppreference tagfile.
`https://en.cppreference.com/w/cpp/container/vector[std::vector,window=\"_blank\"]<xref:reference:boost/urls/url_view.adoc[url_view]>`
Nested symbols
The extension supports nested symbols:
cpp:boost::urls::url_view_base::segments[]
This will render as a link to the boost::urls::url_view_base::segments
class in the boost-url-doxygen.tag.xml
tagfile.
`xref:reference:boost/urls/url_view_base/segments.adoc[boost::urls::url_view_base::segments]`
Which is the page for the boost::urls::url_view_base::segments
symbol
defined in the tagfile rather than only boost::urls::url_view_base
.
Sometimes there's no page for the nested symbol in the tagfile, so the link will redirect to the page for the parent symbol.
cpp:std::vector::iterator[]
This will render as a link to the std::vector
class in the
cppreference tagfile:
`https://en.cppreference.com/w/cpp/container/vector[std::vector::iterator,window=\"_blank\"]`
Which renders as
https://en.cppreference.com/w/cpp/container/vector[std::vector::iterator,window="blank"]
.
Note that there's no page for std::vector::iterator
in cppreference,
so the link will redirect to the page for the parent std::vector
symbol.
Templates and nested symbols can also be combined:
cpp:std::vector<url_view_base::segments>::iterator[]
This will render as a link to the
std::vector<url_view_base::segments>::iterator
class in the
cppreference tagfile.
`https://en.cppreference.com/w/cpp/container/vector[std::vector,window="_blank"]<xref:reference:boost/urls/url_view_base/segments.adoc[url_view_base::segments]>::https://en.cppreference.com/w/cpp/container/vector[std::vector::iterator,window="_blank"]
`
Replacing target names
The extension can replace the target names of the links.
cpp:std::vector[sequential container]
This will render as a link to the std::vector
class in the
cppreference tagfile with the text "sequential container".
`https://en.cppreference.com/w/cpp/container/vector[sequential container,window="_blank"]`
Which renders as
https://en.cppreference.com/w/cpp/container/vector[sequential container,window="_blank"]
.
When providing custom text for a template class, the extension will only link the main symbol:
cpp:std::vector<int>[sequential container]
This will render as a link to the std::vector
class in the
cppreference tagfile with the text "sequential container".
`https://en.cppreference.com/w/cpp/container/vector[sequential container,window="_blank"]`
Which also renders as
https://en.cppreference.com/w/cpp/container/vector[sequential container,window="_blank"]
.
cpp:url_view_base::segments[URL segments]
This will render as a link to the boost::urls::url_view_base::segments
class in the boost-url-doxygen.tag.xml
tagfile with the text "URL
segments".
`xref:reference:boost/urls/url_view_base/segments.adoc[URL segments]`