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@xxxxxxxxxxxxxxxxxxx http://lists.infradead.org/mailman/listinfo/barebox
