[flashrom] [PATCH] Various manpage fixes and improvements

[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 <uwe at hermann-uwe.de>
>
> 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 <c-d.hailfinger.devel.2006 at gmx.net>

Regards,
Carl-Daniel

-- 
http://www.hailfinger.org/