generated command references sometimes render a solid blob of text

[Sascha Hauer]

On Tue, Jul 01, 2014 at 08:43:34AM -0400, Robert P. J. Day wrote:
> 
>   i'm sure everyone else already knows this, but some of the HTML
> files generated for the command reference list sometimes render the
> synopsis or description as a single, unbroken blob of text. for
> example, the reference page for "addpart" has a single line for the
> entire Description field. another example: the Synopsis field for the
> "let" command. and so on.
> 
>   it's easy to see that the .rst files that are created don't properly
> handle paragraph breaks or lists. so is that just a known issue?
> 
>   oh, and one more oddity. if you look at the generated page for the
> "let" command, it appears that the the double hyphen is replaced by a
> longer "em" hyphen. here's part of the generated let.rst file:
> 
> Synopsis
> ^^^^^^^^
> Supported operations are in order of decreasing precedence:
> X++, X--
> ++X, --X
> +X, -X
> !X, ~X
> ...
> 
> but look what shows up in the generated HTML file:
> 
>   X++, X– ++X, –X +X, -X
> 
> notice how occurrences of "--" in the .rst file are replaced by the
> longer hyphen in the HTML file. just an observation.

I think we have to live with this for a while. Our options are:

- reformat Documentation/commands/*.rst manually and no longer
  autogenerate them. It won't take long until they get out of
  sync with the in-binary help texts. No good option
- Add some additional BAREBOX_CMD_HELP_* Macros for special
  cases in some commands like the 'let' command. Could be a
  interim solution
- Instead of rendering Documentation/commands/*.rst from the
  C source files we could do the other way round: render
  the in-binary command help texts from Documentation/commands/*.rst.

I like the last option. sphinx has a plain text renderer. This
could be used to generate <command>.txt files which then could
be included into an environment snippet. help <command> could
be a shortcut to cat /doc/commands/<command>.txt.

Sascha

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |