SWI-Prolog / packages-pldoc

The SWI-Prolog documentation system
6 stars 14 forks source link

Verbatim text does not work in itemizations #31

Open triska opened 7 years ago

triska commented 7 years ago

In the documentation of crypto_data_encrypt/4, I would like to format text as follows:

So, I use:

%     * =|chacha20-poly1305|=
%       Description1
%
%     * =|aes-128-cbc|=
%       Description2
%
%     * =|aes-128-gcm|=
%       Description3

As result, I unexpectedly get:


=() | chacha20()-poly1305()|=()
    Description1 
=() | aes()- 128-cbc()|=()
    Description2 
=() | aes()- 128-gcm()|=()
    Description3 

The issue here seems to be that verbatim text, i.e., =|...|= is not recognized as an item of the itemization if there are also additional descriptions present.

JanWielemaker commented 7 years ago

Cute. The rule applied is that if all first lines of all items are valid Prolog terms we render the Prolog terms and make lists like

  * Term
     Description

Now, =|chacha20-poly1305|= parses as a Prolog term. The rendering obviously fails badly. That is a bug, but if all worked right the result would still be =|chacha20-poly1305|=. If these are atoms, please write 'chacha20-poly1305'. The quote is lost in the rendering, but this can (and should) be fixed.

If you want a description list without Prolog terms, use the variant derived from Twiki:

  $ =|label|= :
  Description

The label is fixed width, but also bold.