[jira] [Commented] (DISPATCH-840) "schema.adoc" contains invalid asciidoc

["Jiri Daněk (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/DISPATCH-840?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17406033#comment-17406033 ] 

Jiri Daněk commented on DISPATCH-840:
-------------------------------------

Docs has changed somewhat since 2017. If I understand the issue correctly, the entities list is currently located in the man page for qdrouterd.conf:

 !qdrouterd.conf.html.png! 

In this rendition, the list looks to be laid out correctly. It is the Manpages artifact from build https://github.com/apache/qpid-dispatch/runs/3431779547

What's weird, though, is that the input .adoc file does contain descriptions for all the attributes, but the descriptions are missing from the {.html}!

{code}
'allowFallbackLinks' (boolean, default='True')::
  Whether this connection is allowed to claim 'qd.fallback' capability for attached links.  This allows endpoints to act as fallback destinations for addresses that have fallback capability enabled.

'sources' (string)::
  A list of source addresses from which users in this group may receive messages. To specify multiple addresses, separate the addresses with either a comma or a space. If you do not specify any addresses, users in this group are not allowed to receive messages from any addresses. You can use the substitution token '${user}' to specify an address that contains a user's authenticated user name. You can use an asterisk ('*') wildcard to match one or more characters in an address. However, this wildcard is only recognized if it is the last character in the address name. You may specify attributes 'sources' or 'sourcePattern' but not both at the same time.

'targets' (string)::
  A list of target addresses to which users in this group may send messages. To specify multiple addresses, separate the addresses with either a comma or a space. If you do not specify any addresses, users in this group are not allowed to send messages to any addresses. You can use the substitution token '${user}' to specify an address that contains a user's authenticated user name. You can use an asterisk ('*') wildcard to match one or more characters in an address. However, this wildcard is only recognized if it is the last character in the address name. You may specify attributes 'targets' or 'targetPattern' but not both at the same time.

'sourcePattern' (string)::
  A wildcarded pattern for matching source addresses from which users in this group may receive messages. The pattern consists of one or more tokens separated by a forward slash '/'. A token can be one of the following: a * character, a # character, or a sequence of characters that do not include /, *, or #.  The * token matches any single token.  The # token matches zero or more tokens. * has higher precedence than #, and exact match has the highest precedence. To specify multiple addresses, separate the addresses with either a comma or a space. You can use the text string '${user}' in a token to specify an address that contains a user's authenticated user name. If you do not specify any addresses, users in this group are not allowed to receive messages from any addresses. You may specify attributes 'sources' or 'sourcePattern' but not both at the same time.

'targetPattern' (string)::
  A wildcarded pattern for matching target addresses to which users in this group may send messages. The pattern consists of one or more tokens separated by a forward slash '/'. A token can be one of the following: a * character, a # character, or a sequence of characters that do not include /, *, or #.  The * token matches any single token.  The # token matches zero or more tokens. * has higher precedence than #, and exact match has the highest precedence. To specify multiple addresses, separate the addresses with either a comma or a space. You can use the text string '${user}' in a token to specify an address that contains a user's authenticated user name. If you do not specify any addresses, users in this group are not allowed to send messages to any addresses. You may specify attributes 'targets' or 'targetPattern' but not both at the same time.
{code}

> "schema.adoc" contains invalid asciidoc
> ---------------------------------------
>
>                 Key: DISPATCH-840
>                 URL: https://issues.apache.org/jira/browse/DISPATCH-840
>             Project: Qpid Dispatch
>          Issue Type: Bug
>          Components: Documentation
>    Affects Versions: 0.8.0
>            Reporter: Ben Hardesty
>            Priority: Major
>             Fix For: Backlog
>
>         Attachments: qdrouterd.conf.html.png
>
>
> The schema_txt.py program [1] generates schema.adoc, which is included in the Dispatch Router book [2]. However, there is an issue with the asciidoc that's generated: the attributes for each configuration and management entity are generated as asciidoc def lists. This is perfectly fine, but some of the attributes don't have descriptions. When one of these "empty" def list entries immediately precedes a new section, that section is not styled properly in the output. To see examples of this, in the Dispatch Router book, search for the following strings:
> * {{=== vhost}}
> * {{=== vhostStats}}
> * {{== Management Operations}}
> To fix this issue, in qdrouter.json, a {{"description": "<value>"}} name-value pair should be added to each attribute that's missing one. If that's not feasible, an alternative would be to update schema_doc.py to properly handle any attribute that doesn't have a description (it looks like lines 70-71 should handle this, but my python's not up to snuff enough to figure out why it isn't).
> [1] - https://github.com/apache/qpid-dispatch/blob/master/doc/book/schema_txt.py
> [2] - https://qpid.apache.org/releases/qpid-dispatch-0.8.0/book/book.html#_configuration_entities



--
This message was sent by Atlassian Jira
(v8.3.4#803005)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@qpid.apache.org
For additional commands, e-mail: dev-help@qpid.apache.org