From 708b5e0d35a4fa6e32648a0a365ef01a698b701f Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Tue, 2 Jun 2009 23:37:56 +0100 Subject: [PATCH] Experiment with alternative longdesc format. --- fish/fish.c | 2 + src/generator.ml | 1670 ++++++++++++++++++++++++++++++------------------------ 2 files changed, 924 insertions(+), 748 deletions(-) diff --git a/fish/fish.c b/fish/fish.c index 96c1a81..488e8aa 100644 --- a/fish/fish.c +++ b/fish/fish.c @@ -256,6 +256,7 @@ main (int argc, char *argv[]) exit (0); } +#if 0 void pod2text (const char *heading, const char *str) { @@ -275,6 +276,7 @@ pod2text (const char *heading, const char *str) fputs (str, fp); pclose (fp); } +#endif /* List is built in reverse order, so mount them in reverse order. */ static void diff --git a/src/generator.ml b/src/generator.ml index bb3744e..c7d208f 100755 --- a/src/generator.ml +++ b/src/generator.ml @@ -250,13 +250,34 @@ and test_init = and seq = cmd list and cmd = string list -(* Note about long descriptions: When referring to another - * action, use the format C (ie. the full name of - * the C function). This will be replaced as appropriate in other - * language bindings. - * - * Apart from that, long descriptions are just perldoc paragraphs. +(* The short description is always a single, short line of plain text. + * Long descriptions use this limited "language" which is converted + * into the required formats on output (eg. perldoc, javadoc, etc.) + * At the top level, long descriptions are a list of paragraphs. *) +type longdesc = para list +and para = + | P of snippet list (* full paragraph *) + | Q of string (* same as P[T str] *) + | ItemList of (snippet list * para) list (* list of items *) + | BulletList of para list (* bullet point list *) + | Note of snippet list (* full note paragraph *) + | QNote of string (* same as Note[T str] *) + | Pre of string list (* preformatted lines *) + | SeeAlso of string list (* see also other commands *) +and snippet = + | T of string (* text *) + | C of string (* code *) + | A of string (* named parameter *) + | X of string (* cross-reference to other command *) + | XA of string * snippet list (* call command with args *) + | XU of string (* cross-reference to unimplemented *) + | XW of string (* cross-reference to wildcard *) + | Em of string (* emphasized text *) + | Man of string * int (* manpage (name, section) *) + | URL of string (* URL *) + | NULL (* "NULL", "undef" etc. *) + | NONNULL (* "non-NULL", "defined", etc. *) (* These test functions are used in the language binding tests. *) @@ -291,39 +312,40 @@ let test_functions = [ ("test0", (RErr, test_all_args), -1, [NotInFish; NotInDocs], [], "internal test function - do not use", - "\ -This is an internal test function which is used to test whether + [ +Q"This is an internal test function which is used to test whether the automatically generated bindings can handle every possible -parameter type correctly. +parameter type correctly."; -It echos the contents of each parameter to stdout. +Q"It echos the contents of each parameter to stdout."; -You probably don't want to call this function."); +Q"You probably don't want to call this function."]); ] @ List.flatten ( List.map ( fun (name, ret) -> [(name, (ret, [String "val"]), -1, [NotInFish; NotInDocs], [], "internal test function - do not use", - "\ -This is an internal test function which is used to test whether + [ +Q"This is an internal test function which is used to test whether the automatically generated bindings can handle every possible -return type correctly. +return type correctly."; + +P[T"It converts string ";A"val";T" to the return type."]; -It converts string C to the return type. +Q"You probably don't want to call this function."]); -You probably don't want to call this function."); (name ^ "err", (ret, []), -1, [NotInFish; NotInDocs], [], "internal test function - do not use", - "\ -This is an internal test function which is used to test whether + [ +Q"This is an internal test function which is used to test whether the automatically generated bindings can handle every possible -return type correctly. +return type correctly."; -This function always returns an error. +Q"This function always returns an error."; -You probably don't want to call this function.")] +Q"You probably don't want to call this function."])] ) test_all_rets ) @@ -336,268 +358,273 @@ let non_daemon_functions = test_functions @ [ ("launch", (RErr, []), -1, [FishAlias "run"; FishAction "launch"], [], "launch the qemu subprocess", - "\ -Internally libguestfs is implemented by running a virtual machine -using L. + [ +P[T"Internally libguestfs is implemented by running a virtual machine +using ";Man("qemu",1);T"."]; -You should call this after configuring the handle -(eg. adding drives) but before performing any actions."); +Q"You should call this after configuring the handle +(eg. adding drives) but before performing any actions."]); ("wait_ready", (RErr, []), -1, [NotInFish], [], "wait until the qemu subprocess launches", - "\ -Internally libguestfs is implemented by running a virtual machine -using L. + [ +P[T"Internally libguestfs is implemented by running a virtual machine +using ";Man("qemu",1);T"."]; -You should call this after C to wait for the launch -to complete."); +P[T"You should call this after ";X"launch"; T" to wait for the launch +to complete."]]); ("kill_subprocess", (RErr, []), -1, [], [], "kill the qemu subprocess", - "\ -This kills the qemu subprocess. You should never need to call this."); + [ +Q"This kills the qemu subprocess. You should never need to call this."]); ("add_drive", (RErr, [String "filename"]), -1, [FishAlias "add"], [], "add an image to examine or modify", - "\ -This function adds a virtual machine disk image C to the + [ +P[T"This function adds a virtual machine disk image ";A"filename";T" to the guest. The first time you call this function, the disk appears as IDE -disk 0 (C) in the guest, the second time as C, and -so on. +disk 0 (";C"/dev/sda";T") in the guest, the second time as ";C"/dev/sdb";T", and +so on."]; -You don't necessarily need to be root when using libguestfs. However +Q"You don't necessarily need to be root when using libguestfs. However you obviously do need sufficient permissions to access the filename for whatever operations you want to perform (ie. read access if you just want to read the image or write access if you want to modify the -image). +image)."; -This is equivalent to the qemu parameter C<-drive file=filename>. +P[T"This is equivalent to the qemu parameter ";C"-drive file=filename";T"."]; -Note that this call checks for the existence of C. This +Note[T"Note that this call checks for the existence of ";A"filename";T". This stops you from specifying other types of drive which are supported -by qemu such as C and C URLs. To specify those, use -the general C call instead."); +by qemu such as ";C"nbd:";T" and ";C"http:";T" URLs. To specify those, use +the general ";X"config";T" call instead."]]); ("add_cdrom", (RErr, [String "filename"]), -1, [FishAlias "cdrom"], [], "add a CD-ROM disk image to examine", - "\ -This function adds a virtual CD-ROM disk image to the guest. + [ +Q"This function adds a virtual CD-ROM disk image to the guest."; -This is equivalent to the qemu parameter C<-cdrom filename>. +P[T"This is equivalent to the qemu parameter ";C"-cdrom filename";T"."]; -Note that this call checks for the existence of C. This +Note[T"Note that this call checks for the existence of ";A"filename";T". This stops you from specifying other types of drive which are supported -by qemu such as C and C URLs. To specify those, use -the general C call instead."); +by qemu such as ";C"nbd:";T" and ";C"http:";T" URLs. To specify those, use +the general ";X"config";T" call instead."]]); ("add_drive_ro", (RErr, [String "filename"]), -1, [FishAlias "add-ro"], [], "add a drive in snapshot mode (read-only)", - "\ -This adds a drive in snapshot mode, making it effectively -read-only. + [ +Q"This adds a drive in snapshot mode, making it effectively +read-only."; -Note that writes to the device are allowed, and will be seen for +Q"Note that writes to the device are allowed, and will be seen for the duration of the guestfs handle, but they are written to a temporary file which is discarded as soon as the guestfs handle is closed. We don't currently have any method to enable -changes to be committed, although qemu can support this. +changes to be committed, although qemu can support this."; -This is equivalent to the qemu parameter -C<-drive file=filename,snapshot=on>. +P[T"This is equivalent to the qemu parameter "; +C"-drive file=filename,snapshot=on";T"."]; -Note that this call checks for the existence of C. This +Note[T"This call checks for the existence of ";A"filename";T". This stops you from specifying other types of drive which are supported -by qemu such as C and C URLs. To specify those, use -the general C call instead."); +by qemu such as ";C"nbd:";T" and ";C"http:";T" URLs. To specify those, use +the general ";X"config";T" call instead."]]); ("config", (RErr, [String "qemuparam"; OptString "qemuvalue"]), -1, [], [], "add qemu parameters", - "\ -This can be used to add arbitrary qemu command line parameters -of the form C<-param value>. Actually it's not quite arbitrary - we + [ +P[T"This can be used to add arbitrary qemu command line parameters +of the form ";C"-qemuparam qemuvalue";T". +Actually it's not quite arbitrary - we prevent you from setting some parameters which would interfere with -parameters that we use. +parameters that we use."]; -The first character of C string must be a C<-> (dash). +P[T"The first character of ";A"qemuparam"; +T" string must be a ";C"-";T" (dash)."]; -C can be NULL."); +P[A"qemuvalue";T" can be ";NULL;T"."]]); ("set_qemu", (RErr, [String "qemu"]), -1, [FishAlias "qemu"], [], "set the qemu binary", - "\ -Set the qemu binary that we will use. + [ +Q"Set the qemu binary that we will use."; -The default is chosen when the library was compiled by the -configure script. +Q"The default is chosen when the library was compiled by the +configure script."; -You can also override this by setting the C -environment variable. +P[T"You can also override this by setting the ";C"LIBGUESTFS_QEMU"; +T" environment variable."]; -Setting C to C restores the default qemu binary."); +P[T"Setting ";A"qemu";T" to ";NULL;T" restores the default qemu binary."]]); ("get_qemu", (RConstString "qemu", []), -1, [], [], "get the qemu binary", - "\ -Return the current qemu binary. + [ +Q"Return the current qemu binary."; -This is always non-NULL. If it wasn't set already, then this will -return the default qemu binary name."); +P[T"This is always ";NONNULL;T". If it wasn't set already, then this will +return the default qemu binary name."]]); ("set_path", (RErr, [String "path"]), -1, [FishAlias "path"], [], "set the search path", - "\ -Set the path that libguestfs searches for kernel and initrd.img. + [ +Q"Set the path that libguestfs searches for kernel and initrd.img."; -The default is C<$libdir/guestfs> unless overridden by setting -C environment variable. +P[T"The default is ";C"$libdir/guestfs";T" unless overridden by setting "; +C"LIBGUESTFS_PATH";T" environment variable."]; -Setting C to C restores the default path."); +P[T"Setting ";A"path";T" to ";NULL;T" restores the default path."]]); ("get_path", (RConstString "path", []), -1, [], [], "get the search path", - "\ -Return the current search path. + [ +Q"Return the current search path."; -This is always non-NULL. If it wasn't set already, then this will -return the default path."); +P[T"This is always ";NONNULL;T". If it wasn't set already, then this will +return the default path."]]); ("set_append", (RErr, [String "append"]), -1, [FishAlias "append"], [], "add options to kernel command line", - "\ -This function is used to add additional options to the -guest kernel command line. + [ +Q"This function is used to add additional options to the +guest kernel command line."; -The default is C unless overridden by setting -C environment variable. +P[T"The default is ";NULL;T" unless overridden by setting "; +C"LIBGUESTFS_APPEND";T" environment variable."]; -Setting C to C means I additional options -are passed (libguestfs always adds a few of its own)."); +P[T"Setting ";A"append";T" to ";NULL;T" means ";Em"no"; +T" additional options are passed +(libguestfs always adds a few of its own)."]]); ("get_append", (RConstString "append", []), -1, [], [], "get the additional kernel options", - "\ -Return the additional kernel options which are added to the -guest kernel command line. + [ +Q"Return the additional kernel options which are added to the +guest kernel command line."; -If C then no options are added."); +P[T"If ";NULL;T" then no options are added."]]); ("set_autosync", (RErr, [Bool "autosync"]), -1, [FishAlias "autosync"], [], "set autosync mode", - "\ -If C is true, this enables autosync. Libguestfs will make a -best effort attempt to run C followed by -C when the handle is closed -(also if the program exits without closing handles). + [ +P[T"If ";A"autosync";T" is true, this enables autosync. Libguestfs will make a +best effort attempt to run ";X"umount_all";T" followed by "; +X"sync";T" when the handle is closed +(also if the program exits without closing handles)."]; -This is disabled by default (except in guestfish where it is -enabled by default)."); +Q"This is disabled by default (except in guestfish where it is +enabled by default)."]); ("get_autosync", (RBool "autosync", []), -1, [], [], "get autosync mode", - "\ -Get the autosync flag."); + [ +Q"Get the autosync flag."]); ("set_verbose", (RErr, [Bool "verbose"]), -1, [FishAlias "verbose"], [], "set verbose mode", - "\ -If C is true, this turns on verbose messages (to C). + [ +P[T"If ";A"verbose";T" is true, this turns on verbose messages +(to ";C"stderr";T")."]; -Verbose messages are disabled unless the environment variable -C is defined and set to C<1>."); +P[T"Verbose messages are disabled unless the environment variable "; +C"LIBGUESTFS_DEBUG";T" is defined and set to ";C"1";T"."]]); ("get_verbose", (RBool "verbose", []), -1, [], [], "get verbose mode", - "\ -This returns the verbose messages flag."); + [ +Q"This returns the verbose messages flag."]); ("is_ready", (RBool "ready", []), -1, [], [], "is ready to accept commands", - "\ -This returns true iff this handle is ready to accept commands -(in the C state). + [ +P[T"This returns true iff this handle is ready to accept commands +(in the ";C"READY";T" state)."]; -For more information on states, see L."); +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); ("is_config", (RBool "config", []), -1, [], [], "is in configuration state", - "\ -This returns true iff this handle is being configured -(in the C state). + [ +P[T"This returns true iff this handle is being configured +(in the ";C"CONFIG";T" state)."]; -For more information on states, see L."); +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); ("is_launching", (RBool "launching", []), -1, [], [], "is launching subprocess", - "\ -This returns true iff this handle is launching the subprocess -(in the C state). + [ +P[T"This returns true iff this handle is launching the subprocess +(in the ";C"LAUNCHING";T" state)."]; -For more information on states, see L."); +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); ("is_busy", (RBool "busy", []), -1, [], [], "is busy processing a command", - "\ -This returns true iff this handle is busy processing a command -(in the C state). + [ +P[T"This returns true iff this handle is busy processing a command +(in the ";C"BUSY";T" state)."]; -For more information on states, see L."); +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); ("get_state", (RInt "state", []), -1, [], [], "get the current state", - "\ -This returns the current state as an opaque integer. This is -only useful for printing debug and internal error messages. + [ +Q"This returns the current state as an opaque integer. This is +only useful for printing debug and internal error messages."; -For more information on states, see L."); +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); ("set_busy", (RErr, []), -1, [NotInFish], [], "set state to busy", - "\ -This sets the state to C. This is only used when implementing -actions using the low-level API. + [ +P[T"This sets the state to ";C"BUSY";T". This is only used when implementing +actions using the low-level API."]; -For more information on states, see L."); +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); ("set_ready", (RErr, []), -1, [NotInFish], [], "set state to ready", - "\ -This sets the state to C. This is only used when implementing -actions using the low-level API. + [ +P[T"This sets the state to ";C"READY";T". This is only used when implementing +actions using the low-level API."]; -For more information on states, see L."); +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); ("end_busy", (RErr, []), -1, [NotInFish], [], "leave the busy state", - "\ -This sets the state to C, or if in C then it leaves the + [ +P[T"This sets the state to ";C"READY";T", or if in ";C"CONFIG"; +T" then it leaves the state as is. This is only used when implementing -actions using the low-level API. +actions using the low-level API."]; -For more information on states, see L."); +P[T"For more information on states, see ";Man("guestfs",3);T"."]]); ] @@ -614,68 +641,68 @@ let daemon_functions = [ ["write_file"; "/new"; "new file contents"; "0"]; ["cat"; "/new"]], "new file contents")], "mount a guest disk at a position in the filesystem", - "\ -Mount a guest disk at a position in the filesystem. Block devices -are named C, C and so on, as they were added to + [ +P[T"Mount a guest disk at a position in the filesystem. Block devices +are named ";C"/dev/sda";T", ";C"/dev/sdb";T" and so on, as they were added to the guest. If those block devices contain partitions, they will have -the usual names (eg. C). Also LVM C-style -names can be used. +the usual names (eg. ";C"/dev/sda1";T"). Also LVM ";C"/dev/VG/LV";T"-style +names can be used."]; -The rules are the same as for L: A filesystem must -first be mounted on C before others can be mounted. Other +P[T"The rules are the same as for ";Man("mount",8);T": A filesystem must +first be mounted on ";C"/";T" before others can be mounted. Other filesystems can only be mounted on directories which already -exist. +exist."]; -The mounted filesystem is writable, if we have sufficient permissions -on the underlying device. +Q"The mounted filesystem is writable, if we have sufficient permissions +on the underlying device."; -The filesystem options C and C are set with this -call, in order to improve reliability."); +P[T"The filesystem options ";C"sync";T" and ";C"noatime";T" are set with this +call, in order to improve reliability."]]); ("sync", (RErr, []), 2, [], [ InitEmpty, Always, TestRun [["sync"]]], "sync disks, writes are flushed through to the disk image", - "\ -This syncs the disk, so that any writes are flushed through to the -underlying disk image. + [ +Q"This syncs the disk, so that any writes are flushed through to the +underlying disk image."; -You should always call this if you have modified a disk image, before -closing the handle."); +Q"You should always call this if you have modified a disk image, before +closing the handle."]); ("touch", (RErr, [String "path"]), 3, [], [InitBasicFS, Always, TestOutputTrue ( [["touch"; "/new"]; ["exists"; "/new"]])], "update file timestamps or create a new file", - "\ -Touch acts like the L command. It can be used to + [ +P[T"Touch acts like the ";Man("touch",1);T" command. It can be used to update the timestamps on a file, or, if the file does not exist, -to create a new zero-length file."); +to create a new zero-length file."]]); ("cat", (RString "content", [String "path"]), 4, [ProtocolLimitWarning], [InitBasicFS, Always, TestOutput ( [["write_file"; "/new"; "new file contents"; "0"]; ["cat"; "/new"]], "new file contents")], "list the contents of a file", - "\ -Return the contents of the file named C. + [ +P[T"Return the contents of the file named ";A"path";T"."]; -Note that this function cannot correctly handle binary files -(specifically, files containing C<\\0> character which is treated -as end of string). For those you need to use the C -function which has a more complex interface."); +P[T"Note that this function cannot correctly handle binary files +(specifically, files containing ";C"\\0";T" character which is treated +as end of string). For those you need to use the ";X"download"; +T" function which has a more complex interface."]]); ("ll", (RString "listing", [String "directory"]), 5, [], [], (* XXX Tricky to test because it depends on the exact format * of the 'ls -l' command, which changes between F10 and F11. *) "list the files in a directory (long format)", - "\ -List the files in C (relative to the root directory, -there is no cwd) in the format of 'ls -la'. + [ +P[T"List the files in ";A"directory";T" (relative to the root directory, +there is no cwd) in the format of ";C"ls -la";T"."]; -This command is mostly useful for interactive sessions. It -is I intended that you try to parse the output string."); +P[T"This command is mostly useful for interactive sessions. It +is ";Em"not";T" intended that you try to parse the output string."]]); ("ls", (RStringList "listing", [String "directory"]), 6, [], [InitBasicFS, Always, TestOutputList ( @@ -684,22 +711,19 @@ is I intended that you try to parse the output string."); ["touch"; "/newest"]; ["ls"; "/"]], ["lost+found"; "new"; "newer"; "newest"])], "list the files in a directory", - "\ -List the files in C (relative to the root directory, -there is no cwd). The '.' and '..' entries are not returned, but -hidden files are shown. - -This command is mostly useful for interactive sessions. Programs -should probably use C instead."); + [ +P[T"List the files in ";A"directory";T" (relative to the root directory, +there is no cwd). The ";C".";T" and ";C"..";T" entries are not returned, but +hidden files are shown."]]); ("list_devices", (RStringList "devices", []), 7, [], [InitEmpty, Always, TestOutputList ( [["list_devices"]], ["/dev/sda"; "/dev/sdb"; "/dev/sdc"; "/dev/sdd"])], "list the block devices", - "\ -List all the block devices. + [ +Q"List all the block devices."; -The full block device names are returned, eg. C"); +P[T"The full block device names are returned, eg. ";C"/dev/sda";T"."]]); ("list_partitions", (RStringList "partitions", []), 8, [], [InitBasicFS, Always, TestOutputList ( @@ -708,13 +732,13 @@ The full block device names are returned, eg. C"); [["sfdisk"; "/dev/sda"; "0"; "0"; "0"; ",10 ,20 ,"]; ["list_partitions"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])], "list the partitions", - "\ -List all the partitions detected on all block devices. + [ +Q"List all the partitions detected on all block devices."; -The full partition device names are returned, eg. C +P[T"The full partition device names are returned, eg. ";C"/dev/sda1"]; -This does not return logical volumes. For that you will need to -call C."); +P[T"This does not return logical volumes. For that you will need to +call ";X"lvs";T"."]]); ("pvs", (RStringList "physvols", []), 9, [], [InitBasicFSonLVM, Always, TestOutputList ( @@ -726,14 +750,14 @@ call C."); ["pvcreate"; "/dev/sda3"]; ["pvs"]], ["/dev/sda1"; "/dev/sda2"; "/dev/sda3"])], "list the LVM physical volumes (PVs)", - "\ -List all the physical volumes detected. This is the equivalent -of the L command. + [ +P[T"List all the physical volumes detected. This is the equivalent +of the ";Man("pvs",8);T" command."]; -This returns a list of just the device names that contain -PVs (eg. C). +P[T"This returns a list of just the device names that contain +PVs (eg. ";C"/dev/sda2";T")."]; -See also C."); +SeeAlso["pvs_full"]]); ("vgs", (RStringList "volgroups", []), 10, [], [InitBasicFSonLVM, Always, TestOutputList ( @@ -747,14 +771,14 @@ See also C."); ["vgcreate"; "VG2"; "/dev/sda3"]; ["vgs"]], ["VG1"; "VG2"])], "list the LVM volume groups (VGs)", - "\ -List all the volumes groups detected. This is the equivalent -of the L command. + [ +P[T"List all the volumes groups detected. This is the equivalent +of the ";Man("vgs",8);T" command."]; -This returns a list of just the volume group names that were -detected (eg. C). +P[T"This returns a list of just the volume group names that were +detected (eg. ";C"VolGroup00";T")."]; -See also C."); +SeeAlso["vgs_full"]]); ("lvs", (RStringList "logvols", []), 11, [], [InitBasicFSonLVM, Always, TestOutputList ( @@ -771,35 +795,38 @@ See also C."); ["lvcreate"; "LV3"; "VG2"; "50"]; ["lvs"]], ["/dev/VG1/LV1"; "/dev/VG1/LV2"; "/dev/VG2/LV3"])], "list the LVM logical volumes (LVs)", - "\ -List all the logical volumes detected. This is the equivalent -of the L command. + [ +P[T"List all the logical volumes detected. This is the equivalent +of the ";Man("lvs",8);T" command."]; -This returns a list of the logical volume device names -(eg. C). +P[T"This returns a list of the logical volume device names +(eg. ";C"/dev/VolGroup00/LogVol00";T")."]; -See also C."); +SeeAlso["lvs_full"]]); ("pvs_full", (RPVList "physvols", []), 12, [], [], (* XXX how to test? *) "list the LVM physical volumes (PVs)", - "\ -List all the physical volumes detected. This is the equivalent -of the L command. The \"full\" version includes all fields."); + [ +P[T"List all the physical volumes detected. This is the equivalent +of the ";Man("pvs",8);T" command. +The \"full\" version includes all fields."]]); ("vgs_full", (RVGList "volgroups", []), 13, [], [], (* XXX how to test? *) "list the LVM volume groups (VGs)", - "\ -List all the volumes groups detected. This is the equivalent -of the L command. The \"full\" version includes all fields."); + [ +P[T"List all the volumes groups detected. This is the equivalent +of the ";Man("vgs",8);T" command. +The \"full\" version includes all fields."]]); ("lvs_full", (RLVList "logvols", []), 14, [], [], (* XXX how to test? *) "list the LVM logical volumes (LVs)", - "\ -List all the logical volumes detected. This is the equivalent -of the L command. The \"full\" version includes all fields."); + [ +P[T"List all the logical volumes detected. This is the equivalent +of the ";Man("lvs",8);T" command. +The \"full\" version includes all fields."]]); ("read_lines", (RStringList "lines", [String "path"]), 15, [], [InitBasicFS, Always, TestOutputList ( @@ -809,175 +836,175 @@ of the L command. The \"full\" version includes all fields."); [["write_file"; "/new"; ""; "0"]; ["read_lines"; "/new"]], [])], "read file as lines", - "\ -Return the contents of the file named C. + [ +P[T"Return the contents of the file named ";A"path";T"."]; -The file contents are returned as a list of lines. Trailing -C and C character sequences are I returned. +P[T"The file contents are returned as a list of lines. Trailing "; +C"LF";T" and ";C"CRLF";T" character sequences are ";Em"not";T" returned."]; -Note that this function cannot correctly handle binary files -(specifically, files containing C<\\0> character which is treated -as end of line). For those you need to use the C -function which has a more complex interface."); +P[T"Note that this function cannot correctly handle binary files +(specifically, files containing ";C"\\0";T" character which is treated +as end of line). For those you need to use the ";XU"read_file"; +T" function which has a more complex interface."]]); ("aug_init", (RErr, [String "root"; Int "flags"]), 16, [], [], (* XXX Augeas code needs tests. *) "create a new Augeas handle", - "\ -Create a new Augeas handle for editing configuration files. + [ +Q"Create a new Augeas handle for editing configuration files. If there was any previous Augeas handle associated with this -guestfs session, then it is closed. +guestfs session, then it is closed."; -You must call this before using any other C -commands. +P[T"You must call this before using any other ";XW"aug_*"; +T" commands."]; -C is the filesystem root. C must not be NULL, -use C instead. +P[A"root";T" is the filesystem root. ";A"root";T" must be ";NONNULL;T", +use ";C"/";T" instead."]; -The flags are the same as the flags defined in -Eaugeas.hE, the logical I of the following -integers: +P[T"The flags are the same as the flags defined in +, the logical OR of the following +integers:"]; -=over 4 +ItemList [ -=item C = 1 +[C"AUG_SAVE_BACKUP";T" = 1"], -Keep the original file with a C<.augsave> extension. + P[T"Keep the original file with a ";C".augsave";T" extension."]; -=item C = 2 +[C"AUG_SAVE_NEWFILE";T" = 2"], -Save changes into a file with extension C<.augnew>, and -do not overwrite original. Overrides C. + P[T"Save changes into a file with extension ";C".augnew";T", and +do not overwrite original. Overrides ";C"AUG_SAVE_BACKUP";T"."]; -=item C = 4 +[C"AUG_TYPE_CHECK";T" = 4"], -Typecheck lenses (can be expensive). + Q"Typecheck lenses (can be expensive)."; -=item C = 8 +[C"AUG_NO_STDINC";T" = 8"], -Do not use standard load path for modules. + Q"Do not use standard load path for modules."; -=item C = 16 +[C"AUG_SAVE_NOOP";T" = 16"], -Make save a no-op, just record what would have been changed. + Q"Make save a no-op, just record what would have been changed."; -=item C = 32 +[C"AUG_NO_LOAD";T" = 32"], -Do not load the tree in C. + P[T"Do not load the tree in ";X"aug_init";T"."]; -=back +]; -To close the handle, you can call C. +P[T"To close the handle, you can call ";X"aug_close";T"."]; -To find out more about Augeas, see L."); +P[T"To find out more about Augeas, see ";URL"http://augeas.net/";T"."]]); ("aug_close", (RErr, []), 26, [], [], (* XXX Augeas code needs tests. *) "close the current Augeas handle", - "\ -Close the current Augeas handle and free up any resources -used by it. After calling this, you have to call -C again before you can use any other -Augeas functions."); + [ +P[T"Close the current Augeas handle and free up any resources +used by it. After calling this, you have to call "; +X"aug_init";T" again before you can use any other +Augeas functions."]]); ("aug_defvar", (RInt "nrnodes", [String "name"; OptString "expr"]), 17, [], [], (* XXX Augeas code needs tests. *) "define an Augeas variable", - "\ -Defines an Augeas variable C whose value is the result -of evaluating C. If C is NULL, then C is -undefined. + [ +P[T"Defines an Augeas variable ";A"name";T" whose value is the result +of evaluating ";A"expr";T". If ";A"expr";T" is ";NULL;T", then ";A"name";T" is +undefined."]; -On success this returns the number of nodes in C, or -C<0> if C evaluates to something which is not a nodeset."); +P[T"On success this returns the number of nodes in ";A"expr";T", or "; +C"0";T" if ";A"expr";T" evaluates to something which is not a nodeset."]]); ("aug_defnode", (RIntBool ("nrnodes", "created"), [String "name"; String "expr"; String "val"]), 18, [], [], (* XXX Augeas code needs tests. *) "define an Augeas node", - "\ -Defines a variable C whose value is the result of -evaluating C. + [ +P[T"Defines a variable ";A"name";T" whose value is the result of +evaluating ";A"expr";T"."]; -If C evaluates to an empty nodeset, a node is created, -equivalent to calling C C, C. -C will be the nodeset containing that single node. +P[T"If ";A"expr";T" evaluates to an empty nodeset, a node is created, +equivalent to calling ";XA("aug_set",[A"expr";A"value"]);T". "; +A"name";T" will be the nodeset containing that single node."]; -On success this returns a pair containing the +Q"On success this returns a pair containing the number of nodes in the nodeset, and a boolean flag -if a node was created."); +if a node was created."]); ("aug_get", (RString "val", [String "path"]), 19, [], [], (* XXX Augeas code needs tests. *) "look up the value of an Augeas path", - "\ -Look up the value associated with C. If C -matches exactly one node, the C is returned."); + [ +P[T"Look up the value associated with ";A"path";T". If ";A"path"; +T" matches exactly one node, the ";C"value";T" is returned."]]); ("aug_set", (RErr, [String "path"; String "val"]), 20, [], [], (* XXX Augeas code needs tests. *) "set Augeas path to value", - "\ -Set the value associated with C to C."); + [ +P[T"Set the value associated with ";A"path";T" to ";A"val";T"."]]); ("aug_insert", (RErr, [String "path"; String "label"; Bool "before"]), 21, [], [], (* XXX Augeas code needs tests. *) "insert a sibling Augeas node", - "\ -Create a new sibling C