generated command references sometimes render a solid blob of text

generated command references sometimes render a solid blob of text

[Robert P. J. Day]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1445 bytes --]


  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.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

[-- Attachment #2: Type: text/plain, Size: 149 bytes --]

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: generated command references sometimes render a solid blob of text

[Holger Schurig]

The Kconfig help entries (the source of the generated command
reference) have been written before python-sphinx have been selected.

So basically we need to go over all of them and make sure that they
render correctly. From my point of view, it doesn't harm if you see
raw ReST formatting while inside "make xconfig".

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: generated command references sometimes render a solid blob of text

[Robert P. J. Day]

On Tue, 1 Jul 2014, Holger Schurig wrote:

> The Kconfig help entries (the source of the generated command
> reference) have been written before python-sphinx have been
> selected.
>
> So basically we need to go over all of them and make sure that they
> render correctly. From my point of view, it doesn't harm if you see
> raw ReST formatting while inside "make xconfig".

  normally, i wouldn't be a big fan of deliberately mangling help info
for the sake of how it will *eventually* be rendered but, in this
case, it seems reasonable.

  and on that note, is it a ReST thing that renders two regular
hyphens as a single, long hyphen? as far as i can tell, that is an
issue only in the let.c command help.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: generated command references sometimes render a solid blob of text

[Jan Lübbe]

On Tue, 2014-07-01 at 16:26 +0200, Holger Schurig wrote:
> The Kconfig help entries (the source of the generated command
> reference) have been written before python-sphinx have been selected.

Actually, the command reference is generated by parsing the macros in
the .c files. The Kconfig entries were changed by hand.

> So basically we need to go over all of them and make sure that they
> render correctly. From my point of view, it doesn't harm if you see
> raw ReST formatting while inside "make xconfig".

I don't think that the Kconfig entries need to contain the full command
documentation.

Regards,
Jan
-- 
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 |


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: generated command references sometimes render a solid blob of text

[Holger Schurig]

> I don't think that the Kconfig entries need to contain the full command
> documentation.

Probably not.

Currently, too many Kconfig options don't have help texts. When I was
new to Barebox, I was puzzled about wether to select an option or not.
Having the complete docs (manually done or auto-generated, doesn't
matter) can be a good help for that.

It's unfortunate that we have now actually 3 places for the help: via
macros in the source, in the Kconfig, and in the *.rst files. The one
in the source code also have an additional property: that options to
commands can depend on Kconfig entries (e.g. "bootm" depends on
CONFIG_CMD_BOOTM_INITRD, CONFIG_OFTREE and CONFIG_CMD_BOOTM_VERBOSE).
That complicates matters even more. Sigh.

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: generated command references sometimes render a solid blob of text

[Robert P. J. Day]

On Wed, 2 Jul 2014, Holger Schurig wrote:

> > I don't think that the Kconfig entries need to contain the full command
> > documentation.
>
> Probably not.
>
> Currently, too many Kconfig options don't have help texts. When I was
> new to Barebox, I was puzzled about wether to select an option or not.
> Having the complete docs (manually done or auto-generated, doesn't
> matter) can be a good help for that.
>
> It's unfortunate that we have now actually 3 places for the help: via
> macros in the source, in the Kconfig, and in the *.rst files. The one
> in the source code also have an additional property: that options to
> commands can depend on Kconfig entries (e.g. "bootm" depends on
> CONFIG_CMD_BOOTM_INITRD, CONFIG_OFTREE and CONFIG_CMD_BOOTM_VERBOSE).
> That complicates matters even more. Sigh.

  gosh, i didn't mean to open quite this can of worms. i'll let those
higher up the food chain decide how to deal with this. i have more
patches to the user manual coming shortly.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: 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 |

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox