From e9ad1650c058b582a68a3d3a018e7df47a17746b Mon Sep 17 00:00:00 2001 From: Nick Mathewson Date: Wed, 20 Dec 2006 17:05:48 +0000 Subject: [PATCH] r11651@Kushana: nickm | 2006-12-20 12:05:04 -0500 Add a maintainer script and a new make target "make check-docs" to get a quick dump of which options are undocumented where, and which documentation refers to nonexistent options. svn:r9160 --- ChangeLog | 2 + Makefile.am | 3 ++ contrib/checkLogs.pl | 0 contrib/checkOptionDocs.pl | 86 ++++++++++++++++++++++++++++++++++++++ doc/TODO | 8 +++- src/or/config.c | 30 +++++++++++++ 6 files changed, 127 insertions(+), 2 deletions(-) mode change 100644 => 100755 contrib/checkLogs.pl create mode 100755 contrib/checkOptionDocs.pl diff --git a/ChangeLog b/ChangeLog index 0d86c2ec31..65e1870715 100644 --- a/ChangeLog +++ b/ChangeLog @@ -31,6 +31,8 @@ Changes in version 0.1.2.5-xxxx - 200?-??-?? network with hosts called @, !, and #. - Add a new address-spec.txt document to describe our special-case addresses: .exit, .onion, and .noconnnect. + - Add a maintainer script to tell us which options are missing + documentation. o Security bugfixes: - Stop sending the HttpProxyAuthenticator string to directory diff --git a/Makefile.am b/Makefile.am index 8268344b2b..60685b0bf0 100644 --- a/Makefile.am +++ b/Makefile.am @@ -66,6 +66,9 @@ check-spaces: src/common/[^as]*.c \ src/or/[^et]*.[ch] src/or/t*.c src/or/eventdns_tor.h +check-docs: + ./contrib/checkOptionDocs.pl + check-logs: ./contrib/checkLogs.pl \ src/*/*.[ch] | sort -n diff --git a/contrib/checkLogs.pl b/contrib/checkLogs.pl old mode 100644 new mode 100755 diff --git a/contrib/checkOptionDocs.pl b/contrib/checkOptionDocs.pl new file mode 100755 index 0000000000..09a29294ee --- /dev/null +++ b/contrib/checkOptionDocs.pl @@ -0,0 +1,86 @@ +#!/usr/bin/perl -w +# $Id +use strict; + +my %options = (); +my %descOptions = (); +my %torrcSampleOptions = (); +my %torrcCompleteOptions = (); +my %manPageOptions = (); + +# Load the canonical list as actually accepted by Tor. +my $mostRecentOption; +open(F, "./src/or/tor --list-torrc-options |") or die; +while () { + next if m!/\[notice\] Tor v0\.!; + if (m!^([A-Za-z0-9_]+)!) { + $mostRecentOption = lc $1; + $options{$mostRecentOption} = 1; + } elsif (m!^ !) { + $descOptions{$mostRecentOption} = 1; + } else { + print "Unrecognized output> "; + print; + } +} +close F; + +# Load the contents of torrc.sample and torrc.complete +sub loadTorrc { + my ($fname, $options) = @_; + local *F; + open(F, "$fname") or die; + while () { + next if (m!##+!); + if (m!#([A-Za-z0-9_]+)!) { + $options->{lc $1} = 1; + } + } + close F; + 0; +} + +loadTorrc("./src/config/torrc.sample.in", \%torrcSampleOptions); +loadTorrc("./src/config/torrc.complete.in", \%torrcCompleteOptions); + +# Try to figure out what's in the man page. + +my $considerNextLine = 0; +open(F, "./doc/tor.1.in") or die; +while () { + if ($considerNextLine and + m!^\\fB([A-Za-z0-9_]+)!) { + $manPageOptions{lc $1} = 1; + } + + if (m!^\.(?:SH|TP)!) { + $considerNextLine = 1; next; + } else { + $considerNextLine = 0; + } +} +close F; + +# Now, display differences: + +sub subtractHashes { + my ($s, $a, $b) = @_; + my @lst = (); + for my $k (keys %$a) { + push @lst, $k unless (exists $b->{$k}); + } + print "$s: ", join(' ', sort @lst), "\n\n"; + 0; +} + +subtractHashes("No online docs", \%options, \%descOptions); +# subtractHashes("Orphaned online docs", \%descOptions, \%options); + +subtractHashes("Not in torrc.complete.in", \%options, \%torrcCompleteOptions); +subtractHashes("Orphaned in torrc.complete.in", \%torrcCompleteOptions, \%options); +subtractHashes("Orphaned in torrc.sample.in", \%torrcSampleOptions, \%options); + +subtractHashes("Not in man page", \%options, \%manPageOptions); +subtractHashes("Orphaned in man page", \%manPageOptions, \%options); + + diff --git a/doc/TODO b/doc/TODO index 0b9fcdddfb..b6668ad853 100644 --- a/doc/TODO +++ b/doc/TODO @@ -135,7 +135,11 @@ N - they don't count toward the 3-strikes rule - should there be some threshold of 503's after which we give up? - Delay when we get a lot of 503s? N - split "router is down" from "dirport shouldn't be tried for a while"? - want a time_t field for got_503_at. + We want a field to hold "when did we last get a 503 from this + directory server." Probably, it should go in local_routerstatus_t, + not in routerinfo_t, since we can try to use servers as directories + before we have their descriptors. Possibly, it should also go in + trusted_dir_server_t. - authorities should *never* 503 a cache, and should never 503 network status requests. They can 503 client descriptor requests when they feel like it. @@ -163,7 +167,7 @@ NR D Get some kind of "meta signing key" to be used solely to sign key, etc. - If we haven't replaced privoxy, lock down its configuration in all packages, as documented in tor-doc-unix.html -N - script to look at config.c, torrc.sample, tor.1.in, to tell us + o script to look at config.c, torrc.sample, tor.1.in, to tell us what's missing in which and notice which descriptions are missing. - Docs diff --git a/src/or/config.c b/src/or/config.c index 7931a9790d..f7a0d26917 100644 --- a/src/or/config.c +++ b/src/or/config.c @@ -1757,6 +1757,31 @@ print_usage(void) "See man page for options, or http://tor.eff.org/ for documentation.\n"); } +/** Print all non-obsolete torrc options. */ +static void +list_torrc_options(void) +{ + int i; + smartlist_t *lines = smartlist_create(); + for (i = 0; _option_vars[i].name; ++i) { + config_var_t *var = &_option_vars[i]; + const char *desc; + if (var->type == CONFIG_TYPE_OBSOLETE || + var->type == CONFIG_TYPE_LINELIST_V) + continue; + desc = config_find_description(&options_format, var->name); + printf("%s\n", var->name); + if (desc) { + wrap_string(lines, desc, 76, " ", " "); + SMARTLIST_FOREACH(lines, char *, cp, { + printf("%s", cp); + tor_free(cp); + }); + smartlist_clear(lines); + } + } +} + /** Last value actually set by resolve_my_address. */ static uint32_t last_resolved_addr = 0; /** @@ -2928,6 +2953,11 @@ options_init_from_torrc(int argc, char **argv) print_usage(); exit(0); } + if (argc > 1 && !strcmp(argv[1], "--list-torrc-options")) { + /* For documenting validating whether we've documented everything. */ + list_torrc_options(); + exit(0); + } if (argc > 1 && (!strcmp(argv[1],"--version"))) { printf("Tor version %s.\n",VERSION);