generated command references sometimes render a solid blob of text
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
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
Quoted 7 lines · Holger Schurig
The
Kconfighelp 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/bareboxQuoted 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 generatedlet.rstfile: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
Quoted 2 lines · Holger Schurig
The
Kconfighelp 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
Quoted 2 lines
I don't think that the
Kconfigentries 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
Quoted 10 lines · Holger Schurig
Quoted 2 lines
I don't think that the
Kconfigentries need to contain the full command documentation.Probably not.
Currently, too many
Kconfigoptions 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 onKconfigentries (e.g. "bootm" depends onCONFIG_CMD_BOOTM_INITRD,CONFIG_OFTREEandCONFIG_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