Re: Command documentation part 1.

[Andrey Borzenkov <arvidjaar@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4397 bytes --]

В Thu, 07 Mar 2013 12:06:56 +0100
Vladimir 'φ-coder/phcoder' Serbinenko <phcoder@gmail.com> пишет:

> On 24.02.2013 08:40, Andrey Borzenkov wrote:
> 
> >  
> >  @menu
> > +* [::                           Check file types and compare values
> >  * acpi::                        Load ACPI tables
> > +* authenticate::                Check whether user is in user list
> > +* background_color::            Set background color for active terminal
> > +* background_image::            Load background image for active terminal
> 
> These are specific to gfxterm, not generic how your patch would suggest.

Is it enough to mention that in command description or we need separate
section for gfxterm-specific commands?

> > +* vbeinfo::                     List available video modes
> 
> vbeinfo is a compatibility alias and is reserved for VBE.
> Perhaps we should start having commands specifically excluded from help
> lists to discourage their use
> 

Is it OK to leave them as comments as Colin suggested (so that they
won't be re-added over and over again)?

> 
> > +@node cmosclean
> > +@subsection cmosclean
> > +
> > +@deffn Command cmosclean byte:bit
> > +Clear value of bit in CMOS at location @var{byte}:@var{bit}.  This command
> > +is available only on PC BIOS platform.
> > +@end deffn
> 
> It's available on all platforms featuring CMOS which are all x86
> (including EFI, coreboot, ieeee1275, and so on), Loongson, Qemu-mips and
> some IEEE1275 platforms (determined at runtime).
> 

Is it OK to change it into "This command is available only on platforms
that support CMOS"?

> > -@deffn Command crc file
> > -Display the CRC32 checksum of @var{file}.
> > +@deffn Command crc arg @dots{}
> > +Alias for @code{hashsum --hash crc32 arg @dots{}}. See command @command{hashsum}
> > +(@pxref{hashsum}) for full description.
> > +@end deffn
> > +
> > +
> > +@node cryptomount
> > +@subsection cryptomount
> > +
> > +@deffn Command cryptomount device|@option{-u} uuid|@option{-a}|@option{-b}
> > +Setup access to encrypted device. If necessary, passphrase
> > +is requested interactively. Option @var{device} configures specific grub device
> > +(@pxref{Naming convention}); option @option{-u} @var{uuid} configures device
> > +with specified @var{uuid}; option @option{-a} configures all encrypted devices;
> 
> Only the ones GRUB supports
> 
> > +option @option{-b} configures all partitions that have boot flag set.
> 
> Last part is wrong. It refers to boot flag in geli container, not the
> one in partmap.

To be honest, this is taken directly from command help; I do not know
myself what geli is. Could you suggest correct description for this
option?

> Also I think it's worth mentioning that luks/geli/... aren't autoloaded.
> 

OK

> > +@node hashsum
> > +@subsection hashsum
> > +
> > +@deffn Command hashsum @option{--hash} hash @option{--keep-going} @option{--uncompress} @option{--check} file [@option{--prefix} dir]|file @dots{}
> > +Compute or verify file hashes. Hash type is selected with option @option{--hash}.
> > +Supported hashes are @samp{crc32}, @samp{md5}, @samp{sha1}, @samp{sha256},
> > +@samp{sha512}.
> 
> Much more hashes are supported. Currently:
> 

OK, I see.


> > +When option @option{--check} is given, it points to a file that contains
> > +list of @var{hash name} pairs. File hash and file name are separated by
> > +single @key{SPACE} or @key{TAB}, one pair on a line. Option @option{--prefix}
> > +may be used to give directory where files are located. Hash verification
> > +stops after the first mismatch was found unless option @option{--keep-going}
> > +was given.
> > +@end deffn
> 
> This is the same format as used by standard UNIX tools.
> 

Sure; do you mean there is no need to document it?

> > @@ -4147,6 +4372,74 @@ will not be shown immediately.
> >  @end deffn
> >  
> >  
> > +@node test
> > +@subsection test
> > +
> > +@deffn Command test expression
> > +Evaluate @var{expression} and return zero exit status if result is true,
> > +non zero status otherwise.
> > +
> > +@var{expression} is one of:
> 
> 
> Did you copy it from somewhere else? Please specify all parts copied
> from anywhere else.
> 

I used "man test" as template. I think the only part that was directly
copied was this sentence.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]