From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Lh6n7-0006Pq-0h for qemu-devel@nongnu.org; Tue, 10 Mar 2009 14:35:01 -0400 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Lh6n5-0006LP-0j for qemu-devel@nongnu.org; Tue, 10 Mar 2009 14:35:00 -0400 Received: from [199.232.76.173] (port=48806 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Lh6n4-0006LC-Sm for qemu-devel@nongnu.org; Tue, 10 Mar 2009 14:34:58 -0400 Received: from mail-fx0-f175.google.com ([209.85.220.175]:49438) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1Lh6n4-0004Wb-DK for qemu-devel@nongnu.org; Tue, 10 Mar 2009 14:34:58 -0400 Received: by fxm23 with SMTP id 23so1776047fxm.34 for ; Tue, 10 Mar 2009 11:34:57 -0700 (PDT) MIME-Version: 1.0 Date: Tue, 10 Mar 2009 20:34:56 +0200 Message-ID: From: Blue Swirl Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit Subject: [Qemu-devel] RFC: Syncing documentation vs. -help vs. qemu_options table Reply-To: qemu-devel@nongnu.org List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel Hi, It would be nice if the documentation about command line switches, -help text and qemu_options table would be kept more easily in sync. In true Qemu tradition, I propose as a solution to make an include file that is parsed once for getting the enums, another time for getopt tables and third time for help message (or these last two may be combined in a more advanced structure). The documentation could be generated from the same file with CPP. The advantage is that all stuff would be in a single location, so developers are less likely to forget to update docs when adding new switches. Considering -parallel switch as an example, the file would contain something like: DEF("parallel", HAS_ARG, QEMU_OPTION_parallel, "-parallel dev redirect the parallel port to char device 'dev'\n") #ifdef DOC @item -parallel @var{dev} Redirect the virtual parallel port to host device @var{dev} (same devices as the serial port). On Linux hosts, @file{/dev/parportN} can be used to use hardware devices connected on the corresponding host parallel port. This option can be used several times to simulate up to 3 parallel ports. Use @code{-parallel none} to disable all parallel ports. #endif /* DOC */ Parsing this in enum mode would yield QEMU_OPTION_parallel, In getopt generation mode: { "parallel", HAS_ARG, QEMU_OPTION_parallel }, And the generated qemu-doc.texi part would contain the texi version. The needed macro magic left as an exercise for the reader. TARGET_I386-only stuff etc. (especially considering the texi) may need more complex #ifdefs. It would also be possible to include the full documentation for each switch into Qemu, so there could be more detailed builtin help for each command line switch (like svn help vs. svn help commit). Comments?