Re: Strangeness in generated xen-command-line.html

[Andrew Cooper <andrew.cooper3@citrix.com>]

On 19/11/14 11:04, Ian Campbell wrote:
> On Wed, 2014-11-19 at 10:52 +0000, Andrew Cooper wrote:
>> On 19/11/14 10:46, Ian Campbell wrote:
>>> On Wed, 2014-11-19 at 10:38 +0000, Ian Campbell wrote:
>>>> I've not been able to find a workaround...
>>> This works for me...
>>>
>>> 8<---------------
>>>
>>> From 3483179d333c47deacfc8c2eb195bf7dc4a555ff Mon Sep 17 00:00:00 2001
>>> From: Ian Campbell <ian.campbell@citrix.com>
>>> Date: Wed, 19 Nov 2014 10:42:18 +0000
>>> Subject: [PATCH] docs: workaround markdown parser error in
>>>  xen-command-line.markdown
>>>
>>> Some versions of markdown (specifically the one in Debian Wheezy, currently
>>> used to generate
>>> http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html) seem to be
>>> confused by nested lists in the middle of multi-paragraph parent list entries
>>> as seen in the com1,com2 entry.
>>>
>>> The effect is that the "Default" section of all following entries are replace
>>> by some sort of hash or checksum (at least, a string of 32 random seeming hex
>>> digits).
>>>
>>> Workaround this issue by making the decriptions of the DPS options a nested
>>> list, moving the existing nested list describing the options for S into a third
>>> level list. This seems to avoid the issue, and is arguably better formatting in
>>> its own right (at least its not a regression IMHO)
>>>
>>> Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
>> I had just identified a different way, but this way is slightly better.
>>
>> If you take out all the blank lines visible in the context below, the
>> resulting HTML will be correctly formatted and rather neater (i.e.
>> without sporadic blank lines).
> Agreed.
>
> 8<------
>
> From 53398a9729d391f1fb7b6f753a0032b1f3604d4d Mon Sep 17 00:00:00 2001
> From: Ian Campbell <ian.campbell@citrix.com>
> Date: Wed, 19 Nov 2014 10:42:18 +0000
> Subject: [PATCH] docs: workaround markdown parser error in
>  xen-command-line.markdown
>
> Some versions of markdown (specifically the one in Debian Wheezy, currently
> used to generate
> http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html) seem to be
> confused by nested lists in the middle of multi-paragraph parent list entries
> as seen in the com1,com2 entry.
>
> The effect is that the "Default" section of all following entries are replace
> by some sort of hash or checksum (at least, a string of 32 random seeming hex
> digits).
>
> Workaround this issue by making the decriptions of the DPS options a nested
> list, moving the existing nested list describing the options for S into a third
> level list. This seems to avoid the issue, and is arguably better formatting in
> its own right (at least its not a regression IMHO)
>
> Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

Reviewed-by: Andrew Cooper <andrew.cooper3@citrix.com>

> ---
> v2: Less blank lines == nicer output.
> ---
>  docs/misc/xen-command-line.markdown |   21 ++++++++-------------
>  1 file changed, 8 insertions(+), 13 deletions(-)
>
> diff --git a/docs/misc/xen-command-line.markdown b/docs/misc/xen-command-line.markdown
> index 0830e5f..b7eaeea 100644
> --- a/docs/misc/xen-command-line.markdown
> +++ b/docs/misc/xen-command-line.markdown
> @@ -247,19 +247,14 @@ Both option `com1` and `com2` follow the same format.
>  * Optionally, a clock speed measured in hz can be specified.
>  * `DPS` represents the number of data bits, the parity, and the number
>    of stop bits.
> -
> -  `D` is an integer between 5 and 8 for the number of data bits.
> -
> -  `P` is a single character representing the type of parity:
> -
> -   * `n` No
> -   * `o` Odd
> -   * `e` Even
> -   * `m` Mark
> -   * `s` Space
> -
> -  `S` is an integer 1 or 2 for the number of stop bits.
> -
> +  * `D` is an integer between 5 and 8 for the number of data bits.
> +  * `P` is a single character representing the type of parity:
> +      * `n` No
> +      * `o` Odd
> +      * `e` Even
> +      * `m` Mark
> +      * `s` Space
> +  * `S` is an integer 1 or 2 for the number of stop bits.
>  * `<io-base>` is an integer which specifies the IO base port for UART
>    registers.
>  * `<irq>` is the IRQ number to use, or `0` to use the UART in poll