[PATCH] Various manpage fixes and improvements

[Uwe Hermann]

See patch.

Uwe.

[Carl-Daniel Hailfinger]

On 06.06.2010 14:50, Uwe Hermann wrote:
> Various manpage fixes and improvements.

Thanks for doing this!
Unfortunately I'm unable to proofread the formatting changes (I don't
know man page syntax well enough), but I did review the textual changes.
> Use [<vendor>:]<board>], not [<vendor>:]<part>], which is more clear.
>
> Mention TSOP48 chips in the description.
>
> Highlight various additional parts in the manpage which were missing
> so far (i.e., make them bold), including cmdline switches and others.
>
> Mention that you can use -VV or -VVV.

-VVV doesn't do anything AFAICS.
> Fix name of the now-renamed 'Supported mainboards' section in -L output.
>
> Mention that ft2232_spi and buspirate_spi only support SPI chips.
>
> Readability and cosmetic improvements, add missing escapes, fix typos.
>
> Signed-off-by: Uwe Hermann
> Index: flashrom.8
>
> --- flashrom.8	(Revision 1033)
> +++ flashrom.8	(Arbeitskopie)
> @@ -61,34 +67,37 @@
>  Erase the flash ROM chip.
>  .TP
>  .B "-V, --verbose"
> -More verbose output.
> +More verbose output. This option can be supplied multiple times
> +(max. 3 times, i.e.
> +.BR -VVV )

max 2 times
-VV
> +for even more debug output.
>  .TP
>  .B "-c, --chip" <chipname>
> -Probe only for specified flash ROM chip. This option takes the chip name as
> +Probe only for the specified flash ROM chip. This option takes the chip name as
>  printed by
>  .B "flashrom -L"
>  without the vendor name. Please note that the chip name is case sensitive.

...without the vendor name as parameter.
> .TP
> -.B "-m, --mainboard" [<vendor>:]<part>
> +.B "-m, --mainboard" [<vendor>:]<board>
>  Override mainboard settings.
>  .sp
>  flashrom reads the coreboot table to determine the current mainboard. If no
>  coreboot table could be read or if you want to override these values, you can
>  specify -m, e.g.:
>  .sp
> -.B "  flashrom --mainboard AGAMI:ARUMA -w agami_aruma.rom"
> +.B "  flashrom --mainboard AGAMI:ARUMA -w agami_aruma.rom"
>  .sp
> -See the 'Supported mainboards' section in the output of 'flashrom -L' for
> -a list of boards which require the specification of the board name, if no
> -coreboot table is found.
> +See the 'Known boards' or 'Known laptops' section in the output
> +of 'flashrom -L' for a list of boards which require the specification of
> +the board name, if no coreboot table is found.
>  .TP
>  .B "-f, --force"
>  Force one or more of the following actions:
>  .sp
> Force chip read and pretend the chip is there.
>
> .sp
> -* Force chip access even if the chip is bigger than max decode size for\
> the flash bus.
>
> +* Force chip access even if the chip is bigger than the maximum decode size\

Either "...decoded size..." or "...supported size...". I prefer "supported".
> for the flash bus.
>
> .sp
> Force erase even if erase is known bad.
>
> .sp
> @@ -111,13 +120,13 @@
>  All addresses are offsets within the file, not absolute addresses!
>  If you only want to update the normal image in a ROM you can say:
>  .sp
> -.B "  flashrom --layout rom.layout --image normal -w agami_aruma.rom"
> +.B "  flashrom --layout rom.layout --image normal -w agami_aruma.rom"
>  .sp
>  To update normal and fallback but leave the VGA BIOS alone, say:
>  .sp
> -.B "  flashrom -l rom.layout -i normal "
> +.B "  flashrom -l rom.layout -i normal "
>  .br
> -.B "           -i fallback -w agami_aruma.rom"
> +.B "           -i fallback -w agami_aruma.rom"
>  .sp
>  Currently overlapping sections are not supported.
>  .TP
> @@ -132,7 +141,10 @@
>  .sp
>  There are many unlisted boards which will work out of the box, without
>  special support in flashrom. Please let us know if you can verify that
> -other boards work or do not work out of the box. For verification you have
> +other boards work or do not work out of the box.
> +.sp
> +.B IMPORTANT:
> +For verification you have
>  to test an ERASE and/or WRITE operation, so make sure you only do that
>  if you have proper means to recover from failure!
>  .TP
> @@ -166,17 +178,17 @@
>  .sp
>  .BR "* it87spi" " (for flash ROMs behind an ITE IT87xx Super I/O LPC/SPI translation unit)"
>  .sp
> -.BR "* ft2232_spi" " (for flash ROMs attached to a FT2232H/FT4232H based USB SPI programmer)"
> +.BR "* ft2232_spi" " (for SPI flash ROMs attached to a FT2232H/FT4232H based USB SPI programmer)"

80 column limit?
> .sp
>  .BR "* serprog" " (for flash ROMs attached to Urja's AVR programmer)"
>  .sp
> -.BR "* buspirate_spi" " (for flash ROMs attached to a Bus Pirate)"
> +.BR "* buspirate_spi" " (for SPI flash ROMs attached to a Bus Pirate)"
>  .sp
> @@ -212,20 +227,22 @@
>  protects only part of the flash (commonly the top end, called boot block),
>  flashrom might encounter an error only after erasing the unprotected part,
>  so running without the board-enable function might be dangerous for erase
> -and write (which includes erase).
> +and write (which also includes the erase step).

I'd like to keep the original wording here because it fits better with
the overall sentence structure.

There's one think I'd love to see changed:
"Please report any bugs at
http://www.flashrom.org/trac/flashrom/newticket, or on the flashrom
mailing list at http://www.flashrom.org/mailman/listinfo/flashrom."
I have no idea how to make a space appear after each URL. Such a space
would help in case anyone uses cut-n-paste or automatic link recognition
which may include the colon or full stop in the URL.

With that in mind, this patch is
Acked-by: Carl-Daniel Hailfinger

Regards,
Carl-Daniel

[Uwe Hermann]

On Sun, Jun 06, 2010 at 05:30:04PM +0200, Carl-Daniel Hailfinger wrote:
> > Mention that you can use -VV or -VVV.
>
> -VVV doesn't do anything AFAICS.

Done.
> > +(max. 3 times, i.e.
> > +.BR -VVV )
>
> max 2 times
> -VV

Done.
> > +for even more debug output.
> >  .TP
> >  .B "-c, --chip" <chipname>
> > -Probe only for specified flash ROM chip. This option takes the chip name as
> > +Probe only for the specified flash ROM chip. This option takes the chip name as
> >  printed by
> >  .B "flashrom -L"
> >  without the vendor name. Please note that the chip name is case sensitive.
>
> ...without the vendor name as parameter.

Done.
> > -* Force chip access even if the chip is bigger than max decode size for\
> > the flash bus.
> >
> > +* Force chip access even if the chip is bigger than the maximum decode size\
>
> Either "...decoded size..." or "...supported size...". I prefer "supported".

Done.
> > -.BR "* ft2232_spi" " (for flash ROMs attached to a FT2232H/FT4232H based USB SPI programmer)"
> > +.BR "* ft2232_spi" " (for SPI flash ROMs attached to a FT2232H/FT4232H based USB SPI programmer)"
>
> 80 column limit?

Fixed, also in a few other places.
> > -and write (which includes erase).
> > +and write (which also includes the erase step).
>
> I'd like to keep the original wording here because it fits better with
> the overall sentence structure.

Done.
> There's one think I'd love to see changed:
> "Please report any bugs at
> http://www.flashrom.org/trac/flashrom/newticket, or on the flashrom
> mailing list at http://www.flashrom.org/mailman/listinfo/flashrom."
> I have no idea how to make a space appear after each URL. Such a space
> would help in case anyone uses cut-n-paste or automatic link recognition
> which may include the colon or full stop in the URL.

Hm, not such a big issue IMHO, but I changed it so that each URL is on
an extra line so it can be copy-pasted.
> With that in mind, this patch is
> Acked-by: Carl-Daniel Hailfinger

Thanks, r1038.

Uwe.