Skip to contentSkip to conversation

generated command references sometimes render a solid blob of text

DISCUSSION Robert P. J. Day 4 participants 7 messages Jul 1, 2014 – Jul 2, 2014

lore
Share & tools
lore
#0 lore raw

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

Signature · 7 lines
========================================================================
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
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox

#1 lore raw

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
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox

#2 lore raw
Quoted 7 lines · 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".

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

Signature · 12 lines
========================================================================
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
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox
#6 lore raw
In reply to Robert P. J. Day
Quoted 24 lines · Robert P. J. Day

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
...

Quoted 6 lines

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

Signature · 9 lines
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
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox
#3 lore raw
In reply to Holger Schurig
Quoted 2 lines · Holger Schurig

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.

Quoted 3 lines

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

Signature · 10 lines
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
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox
#4 lore raw
Quoted 2 lines

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
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox

#5 lore raw
Quoted 10 lines · Holger Schurig
Quoted 2 lines

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.

Quoted 6 lines

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

Signature · 12 lines
========================================================================
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
[email protected]
http://lists.infradead.org/mailman/listinfo/barebox