On Tue, Jan 07, 2025 at 06:32:23PM +0000, Gavin Smith wrote: > Some comments are below: > > > First block: > > > > > > The defaults for the @if... conditionals depend on the output format: > > if generating Docbook, --ifdocbook is on and the others are off; > > if generating HTML, --ifhtml is on and the others are off; > > if generating Info, --ifinfo is on and the others are off; > > if generating plain text, --ifplaintext is on and the others are off; > > if generating LaTeX, --iflatex is on and the others are off; > > if generating XML, --ifxml is on and the others are off. > > So this part of the help message could be condensed in my opinion. Do > you want to leave me to edit it?
Please do. > > Second block: > > > > > > Examples: > > makeinfo foo.texi write Info to foo's @setfilename > > makeinfo --html foo.texi write HTML to @setfilename > > makeinfo --xml foo.texi write Texinfo XML to @setfilename > > makeinfo --docbook foo.texi write Docbook XML to @setfilename > > makeinfo --plaintext foo.texi write plain text to standard output > > makeinfo --pdf foo.texi write PDF using texi2dvi > > > > makeinfo --html --no-headers foo.texi write html without node lines, > > menus > > makeinfo --number-sections foo.texi write Info with numbered sections > > makeinfo --no-split foo.texi write one Info file however big > > > > > > Should I split or not? > > It could be fine to split this, as the examples should change to "texi2any" > (or argv[0]; see below) rather than "makeinfo". > > These examples are also out of date: > > > makeinfo foo.texi write Info to foo's @setfilename > > There is no requirement to have a @setfilename line in foo.texi. I could > edit this as well? Yes, I noted that the example was not good too. Please edit and split to your liking. > One problem with splitting this by lines is that the first part of each line > is not to be translated, and the translators would have to realise this. In > theory there can be common variables between the example code and the > description, as in: > > $ help2man --help | grep opt-include > -I, --opt-include=FILE include material from `FILE' if it exists > $ LANGUAGE=fr help2man --help | grep opt-include > -I, --opt-include=FICHIER ajouter du texte depuis « FICHIER », > > so it is not wrong to have the example code included in the translated > string, and this may be simpler and more consistent with the other parts > of the help message. Ok. > > (In the second block, I will replace makeinfo by the actual command name, > > so every occurence of makeinfo should be replaced by %s.) > > This has the issue that if a long directory path is used to invoke the > program the example might have lines that are too long. In fact, I intend to use the basename in the message, as we do in general, without the directory path. > Some programs I checked didn't do it this way: > > $ /usr/bin/tar --help | head -n 8 > Usage: tar [OPTION...] [FILE]... > GNU 'tar' saves many files together into a single tape or disk archive, and > can > restore individual files from the archive. > > Examples: > tar -cf archive.tar foo bar # Create archive.tar from files foo and bar. > tar -tvf archive.tar # List all files in archive.tar verbosely. > tar -xf archive.tar # Extract all files from archive.tar. > > Note "tar", not "/usr/bin/tar" in the help message. That's actually what I wanted to do... > But also: > > $ /usr/bin/bash --help | grep Type > Type `/usr/bin/bash -c "help set"' for more information about shell options. > Type `/usr/bin/bash -c help' for more information about shell builtin > commands.
