Is your feature request related to a problem? Please describe.
In an OpenAPI specification, it is common to use enumerations or lists to for instance describe the semantics of enum values
take for example the following field:
vehicleType:
type: integer
enum: [ 1, 2, 3 ]
x-enum-varnames: [ CAR_1, TRUCK_2, MOPED_3 ]
description: |
Type of Vehicle:
* 1 - Automobile / Car
* 2 - Truck
* 3 - Moped / Motor-assisted bicycle
The AsciiDoc generator puts this multi-line description into a Table cell and for some reason assumes that table cell content can only be one-line in AsciiDoc. Hence it removes all the line-breaks, which looks like this:
| vehicleType
|
|
| <<Integer>>
| Type of Vehicle: * 1 - Automobile / Car * 2 - Truck * 3 - Moped / Motor-assisted bicycle
| _Enum:_ 1, 2, 3
Unfortunately, when rendering this with AsciiDoc, it fill the table cells with a single floating text block, which is not readable at all. Removing the line breaks in essence broke the formatting and makes it impossible to use paragraphs, enumerations, lists, etc. which are all very useful for structuring information and making it readable.
If AsciiDoc table cells would indeed only support one-line content, then I could completely understand this. However, in AsciiDoc it is possible to turn a table cell into an AsciiDoc-cell by putting the letter 'a' before the '|' (Pipe symbol) like this:
| vehicleType
|
|
| <<Integer>>
a| Type of Vehicle:
* 1 - Automobile / Car
* 2 - Truck
* 3 - Moped / Motor-assisted bicycle
| _Enum:_ 1, 2, 3
This is rendered by AsciiDoc as a table cell with beautiful, multi-line content which can contain paragraphs, enumerations, lists and all the other benefits that full AsciiDoc support brings with it.
Describe the solution you'd like
My proposal is simple:
Do not remove the line breaks, but use an AsciiDoc cell (the one with the 'a' char before the pipe symbol) instead (at least for multi-line descriptions). This allows your users to make full use of what the AsciiDoc / Antora ecosystem has to offer instead of unneccessarily limiting them to one-line descriptions. I know that OpenAPI descriptions are formatted in CommonMark and not in AsciiDoc, but
- this is much more useful than limiting everyone generating to AsciiDoc to one-line descriptions, and
- the overlap between CommonMark and AsciiDoc is sufficiently large to make this useful even when using multiple generators.
Describe alternatives you've considered
I wasted several hours trying to write a python script that put the line breaks back in at the correct locations in order to fix the formatting, but information that is removed cannot be recovered and the only right way to solve this issue is to fix the generator.
Additional context
How it is now:
How it should be:
Is your feature request related to a problem? Please describe.
In an OpenAPI specification, it is common to use enumerations or lists to for instance describe the semantics of enum values
take for example the following field:
The AsciiDoc generator puts this multi-line description into a Table cell and for some reason assumes that table cell content can only be one-line in AsciiDoc. Hence it removes all the line-breaks, which looks like this:
Unfortunately, when rendering this with AsciiDoc, it fill the table cells with a single floating text block, which is not readable at all. Removing the line breaks in essence broke the formatting and makes it impossible to use paragraphs, enumerations, lists, etc. which are all very useful for structuring information and making it readable.
If AsciiDoc table cells would indeed only support one-line content, then I could completely understand this. However, in AsciiDoc it is possible to turn a table cell into an AsciiDoc-cell by putting the letter 'a' before the '|' (Pipe symbol) like this:
This is rendered by AsciiDoc as a table cell with beautiful, multi-line content which can contain paragraphs, enumerations, lists and all the other benefits that full AsciiDoc support brings with it.
Describe the solution you'd like
My proposal is simple:
Do not remove the line breaks, but use an AsciiDoc cell (the one with the 'a' char before the pipe symbol) instead (at least for multi-line descriptions). This allows your users to make full use of what the AsciiDoc / Antora ecosystem has to offer instead of unneccessarily limiting them to one-line descriptions. I know that OpenAPI descriptions are formatted in CommonMark and not in AsciiDoc, but
Describe alternatives you've considered
I wasted several hours trying to write a python script that put the line breaks back in at the correct locations in order to fix the formatting, but information that is removed cannot be recovered and the only right way to solve this issue is to fix the generator.
Additional context
How it is now:
How it should be: