[PATCH] Document --output in the man page

[Carl-Daniel Hailfinger]

Document --output in the man page.
Add an examples section to the man page.

Signed-off-by: Carl-Daniel Hailfinger

Index: flashrom-logfile_manpage/flashrom.8
===================================================================
--- flashrom-logfile_manpage/flashrom.8	(Revision 1549)
+++ flashrom-logfile_manpage/flashrom.8	(Arbeitskopie)
@@ -8,6 +8,7 @@
          [\fB-c\fR <chipname>] \
 [\fB-l\fR <file>]
          [\fB-i\fR <image>] [\fB-p\fR <programmername>[:<parameters>]]
+         [\fB-o\fR <logfile>]
 .SH DESCRIPTION
 .B flashrom
 is a utility for detecting, reading, writing, verifying and erasing flash
@@ -220,6 +221,13 @@
 .B "-h, --help"
 Show a help text and exit.
 .TP
+.B "-o, --output <logfile>"
+Save a full debug log to
+.BR <logfile> .
+If the file already exists, it will be overwritten. This is the recommended
+way to gather logs from flashrom because they will be verbose even if the
+on-screen messages are not verbose.
+.TP
 .B "-R, --version"
 Show version information and exit.
 .SH PROGRAMMER SPECIFIC INFO
@@ -697,6 +705,25 @@
 is the Linux device node for your SPI controller.
 .sp
 Please note that the linux_spi driver only works on Linux.
+.SH EXAMPLES
+To back up and update your BIOS, run
+.sp
+.B flashrom -p internal -r backup.rom -o backuplog.txt
+.br
+.B flashrom -p internal -w newbios.rom -o writelog.txt
+.sp
+Please make sure to copy backup.rom to some external media before you try
+to write. That makes offline recovery easier.
+.br
+If writing fails and flashrom complains about the chip being in an unknown
+state, you can try to restore the backup by running
+.sp
+.B flashrom -p internal -w backup.rom -o restorelog.txt
+.sp
+If you encounter any problems, please contact us and supply
+backuplog.txt, writelog.txt and restorelog.txt. See section
+.B BUGS
+for contact info.
 .SH EXIT STATUS
 flashrom exits with 0 on success, 1 on most failures but with 2 if /dev/mem
 (/dev/xsvc on Solaris) can not be opened and with 3 if a call to mmap() fails.

[Paul Menzel]

Am Samstag, den 21.07.2012, 04:26 +0200 schrieb Carl-Daniel Hailfinger:
> Document --output in the man page.
> Add an examples section to the man page.
>
> Signed-off-by: Carl-Daniel Hailfinger
> Index: flashrom-logfile_manpage/flashrom.8
>
> --- flashrom-logfile_manpage/flashrom.8	(Revision 1549)
> +++ flashrom-logfile_manpage/flashrom.8	(Arbeitskopie)
> @@ -8,6 +8,7 @@
>           [\fB-c\fR <chipname>] \
>  [\fB-l\fR <file>]
>           [\fB-i\fR <image>] [\fB-p\fR <programmername>[:<parameters>]]
>     [\fB-o\fR <logfile>]
>
> .SH DESCRIPTION
>  .B flashrom
>  is a utility for detecting, reading, writing, verifying and erasing flash
> @@ -220,6 +221,13 @@
>  .B "-h, --help"
>  Show a help text and exit.
>  .TP
> +.B "-o, --output <logfile>"
> +Save a full debug log to

I am unsure about the »a« in there. But I am no native speaker, so I
everything might be fine.
> +.BR <logfile> .
> +If the file already exists, it will be overwritten. This is the recommended
> +way to gather logs from flashrom because they will be verbose even if the
> +on-screen messages are not verbose.
> +.TP
>  .B "-R, --version"
>  Show version information and exit.
>  .SH PROGRAMMER SPECIFIC INFO
> @@ -697,6 +705,25 @@
>  is the Linux device node for your SPI controller.
>  .sp
>  Please note that the linux_spi driver only works on Linux.
> +.SH EXAMPLES
> +To back up and update your BIOS, run
> +.sp
> +.B flashrom -p internal -r backup.rom -o backuplog.txt
> +.br
> +.B flashrom -p internal -w newbios.rom -o writelog.txt
> +.sp
> +Please make sure to copy backup.rom to some external media before you try
> +to write. That makes offline recovery easier.
> +.br
> +If writing fails and flashrom complains about the chip being in an unknown
> +state, you can try to restore the backup by running
> +.sp
> +.B flashrom -p internal -w backup.rom -o restorelog.txt
> +.sp
> +If you encounter any problems, please contact us and supply
> +backuplog.txt, writelog.txt and restorelog.txt. See section
> +.B BUGS
> +for contact info.
>  .SH EXIT STATUS
>  flashrom exits with 0 on success, 1 on most failures but with 2 if /dev/mem
>  (/dev/xsvc on Solaris) can not be opened and with 3 if a call to mmap() fails.

Acked-by: Paul Menzel

Thanks,

Paul

[Carl-Daniel Hailfinger]

Am 21.07.2012 10:46 schrieb Paul Menzel:
> Am Samstag, den 21.07.2012, 04:26 +0200 schrieb Carl-Daniel Hailfinger:
> > Document --output in the man page.
> > Add an examples section to the man page.
> >
> > Signed-off-by: Carl-Daniel Hailfinger
> > Index: flashrom-logfile_manpage/flashrom.8
> >
> > --- flashrom-logfile_manpage/flashrom.8	(Revision 1549)
> > +++ flashrom-logfile_manpage/flashrom.8	(Arbeitskopie)
> > @@ -220,6 +221,13 @@
> >  .B "-h, --help"
> >  Show a help text and exit.
> >  .TP
> > +.B "-o, --output <logfile>"
> > +Save a full debug log to
>
> I am unsure about the »a« in there. But I am no native speaker, so I
> everything might be fine.

Changed.
> Acked-by: Paul Menzel

Thanks for the review!

New version.

Document --output in the man page.
Add an examples section to the man page.

Signed-off-by: Carl-Daniel Hailfinger 
Acked-by: Paul Menzel

Index: flashrom-logfile_manpage/flashrom.8
===================================================================
--- flashrom-logfile_manpage/flashrom.8	(Revision 1549)
+++ flashrom-logfile_manpage/flashrom.8	(Arbeitskopie)
@@ -8,6 +8,7 @@
          [\fB-c\fR <chipname>] \
 [\fB-l\fR <file>]
          [\fB-i\fR <image>] [\fB-p\fR <programmername>[:<parameters>]]
+         [\fB-o\fR <logfile>]
 .SH DESCRIPTION
 .B flashrom
 is a utility for detecting, reading, writing, verifying and erasing flash
@@ -220,6 +221,13 @@
 .B "-h, --help"
 Show a help text and exit.
 .TP
+.B "-o, --output <logfile>"
+Save the full debug log to
+.BR <logfile> .
+If the file already exists, it will be overwritten. This is the recommended
+way to gather logs from flashrom because they will be verbose even if the
+on-screen messages are not verbose.
+.TP
 .B "-R, --version"
 Show version information and exit.
 .SH PROGRAMMER SPECIFIC INFO
@@ -697,6 +705,25 @@
 is the Linux device node for your SPI controller.
 .sp
 Please note that the linux_spi driver only works on Linux.
+.SH EXAMPLES
+To back up and update your BIOS, run
+.sp
+.B flashrom -p internal -r backup.rom -o backuplog.txt
+.br
+.B flashrom -p internal -w newbios.rom -o writelog.txt
+.sp
+Please make sure to copy backup.rom to some external media before you try
+to write. That makes offline recovery easier.
+.br
+If writing fails and flashrom complains about the chip being in an unknown
+state, you can try to restore the backup by running
+.sp
+.B flashrom -p internal -w backup.rom -o restorelog.txt
+.sp
+If you encounter any problems, please contact us and supply
+backuplog.txt, writelog.txt and restorelog.txt. See section
+.B BUGS
+for contact info.
 .SH EXIT STATUS
 flashrom exits with 0 on success, 1 on most failures but with 2 if /dev/mem
 (/dev/xsvc on Solaris) can not be opened and with 3 if a call to mmap() fails.

[Carl-Daniel Hailfinger]

Am 21.07.2012 18:54 schrieb Carl-Daniel Hailfinger:
> Document --output in the man page.
> Add an examples section to the man page.
>
> Signed-off-by: Carl-Daniel Hailfinger 
> Acked-by: Paul Menzel

Committed in r1550.

Regards,
Carl-Daniel