updated syntax for src/ markdown files,renamed markdown files

src/mainpage.md → src/README.md

@@ -1,3 +1,5 @@
+# src/ files
+
 @mainpage Tor source reference
 
 @tableofcontents
@@ -83,34 +85,34 @@ will be scheduled.
 The codebase is divided into a few top-level subdirectories, each of
 which contains several sub-modules.
 
-   - \refdir{ext} -- Code maintained elsewhere that we include in the Tor
-     source distribution.  You should not edit this code if you can
-     avoid it: we try to keep it identical to the upstream versions.
+ - **\refdir{ext}** -- Code maintained elsewhere that we include in the Tor
+source distribution.  You should not edit this code if you can
+avoid it: we try to keep it identical to the upstream versions.
 
-   - \refdir{lib} -- Lower-level utility code, not necessarily
-     tor-specific.
+ - **\refdir{lib}** -- Lower-level utility code, not necessarily
+tor-specific.
 
-   - `trunnel` -- Automatically generated code (from the Trunnel
-     tool): used to parse and encode binary formats.
+ - `trunnel` -- Automatically generated code (from the Trunnel
+tool): used to parse and encode binary formats.
 
-   - \refdir{core} -- Networking code that is implements the central
-     parts of the Tor protocol and main loop.
+ - **\refdir{core}** -- Networking code that is implements the central
+parts of the Tor protocol and main loop.
 
-   - \refdir{feature} -- Aspects of Tor (like directory management,
-     running a relay, running a directory authorities, managing a list of
-     nodes, running and using onion services) that are built on top of the
-     mainloop code.
+ - **\refdir{feature}** -- Aspects of Tor (like directory management,
+running a relay, running a directory authorities, managing a list of
+nodes, running and using onion services) that are built on top of the
+mainloop code.
 
-   - \refdir{app} -- Highest-level functionality; responsible for setting
-     up and configuring the Tor daemon, making sure all the lower-level
-     modules start up when required, and so on.
+ - **\refdir{app}** -- Highest-level functionality; responsible for setting
+up and configuring the Tor daemon, making sure all the lower-level
+modules start up when required, and so on.
 
-   - \refdir{tools} -- Binaries other than Tor that we produce.
-      Currently this is tor-resolve, tor-gencert, and the tor_runner.o helper
-      module.
+ - **\refdir{tools}** -- Binaries other than Tor that we produce.
+Currently this is tor-resolve, tor-gencert, and the tor_runner.o helper
+module.
 
-   - `test` -- unit tests, regression tests, and a few integration
-     tests.
+ - `test` -- unit tests, regression tests, and a few integration
+tests.
 
 In theory, the above parts of the codebase are sorted from highest-level to
 lowest-level, where high-level code is only allowed to invoke lower-level
@@ -149,3 +151,17 @@ more connection types.
 
 A 'Node' (node_t) is a view of a Tor instance's current knowledge and opinions
 about a Tor relay or bridge.
+
+
+## Other Document
+
+ - [src/app](app/README.md)
+ - [src/config](config/README.md)
+ - [src/core](core/README.md)
+ - [src/ext](ext/README.md)
+ - [src/feature](feature/README.md)
+ - [src/lib](lib/README.md)
+ - [src/test](test/README.md)
+ - [src/tools](tools/README.md)
+ - [src/trunnel](trunnel/README.md)
+

src/app/app.md → src/app/README.md

@@ -1,11 +1,13 @@
+# src/app files
+
 @dir /app
 @brief app: top-level entry point for Tor
 
 The "app" directory has Tor's main entry point and configuration logic,
 and is responsible for initializing and managing the other modules in
 Tor.
 
-The modules in "app" are:
+**The modules in "app" are:**
 
-   - \refdir{app/config} -- configuration and state for Tor
-   - \refdir{app/main} -- Top-level functions to invoke the rest or Tor.
+ - \refdir{app/config} -- configuration and state for Tor
+ - \refdir{app/main} -- Top-level functions to invoke the rest or Tor.

src/config/README → src/config/README.md

@@ -1,41 +1,43 @@
+# src/config files
+
 This directory has configuration files that ship with Tor.  They include:
 
-geoip
-geoip6
+ - geoip
+ - geoip6
 
-    Geoip files for IPv4 and IPv6
+## Geoip files for IPv4 and IPv6
 
-torrc.minimal, torrc.sample:
+### torrc.minimal, torrc.sample:
 
-    generated from torrc.minimal.in and torrc.sample.in by autoconf.
+generated from torrc.minimal.in and torrc.sample.in by autoconf.
 
-torrc.minimal.in:
+### torrc.minimal.in:
 
-    A very small torrc, suitable for installation by default in
-    /etc/tor/torrc.
+## A very small torrc, suitable for installation by default in
+/etc/tor/torrc.
 
-    We try to change torrc.minimal.in as infrequently as possible,
-    since doing so makes the users of many packages have to re-build
-    their torrc files.
+We try to change torrc.minimal.in as infrequently as possible,
+since doing so makes the users of many packages have to re-build
+their torrc files.
 
 
-torrc.minimal.in-staging
+## torrc.minimal.in-staging
 
-    This is where we stage changes to torrc.minimal.in over time so
-    that when we have a change large enough to warrant a new
-    torrc.minimal.in, we can copy all the other changes over
-    wholesale.
+This is where we stage changes to torrc.minimal.in over time so
+that when we have a change large enough to warrant a new
+torrc.minimal.in, we can copy all the other changes over
+wholesale.
 
-torrc.sample.in:
+## torrc.sample.in:
 
-    A verbose, discursive, batteries-included torrc.  Suitable for
-    letting people know how to set up various options, including those
-    most people shouldn't mess with.
+A verbose, discursive, batteries-included torrc.  Suitable for
+letting people know how to set up various options, including those
+most people shouldn't mess with.
 
 
 ==============================
 
-On the geoip format:
+## On the geoip format:
 
 Our geoip files are line-oriented. Any empty line, or line starting
 with a #, is ignored.
@@ -48,7 +50,7 @@ addresses, with no brackets. In both cases CC is a two-character
 country code.
 
 The semantic meaning of a line START,END,CC is that all addresses
-between START and END _inclusive_ should be mapped to the country code
+between START and END **_inclusive_** should be mapped to the country code
 CC.
 
 We guarantee that all entries within these files are disjoint --
@@ -59,6 +61,6 @@ sorted in numerically ascending order by address.
 Thus, one effective search algorithm here is to perform a binary
 search on all the entries in the file.
 
-Note that there _are_ "gaps" in these databases: not every possible
+Note that there **_are_** "gaps" in these databases: not every possible
 address maps to a country code. In those cases, Tor reports the
 country as ??.

src/core/core.md → src/core/README.md

@@ -1,3 +1,5 @@
+# src/core files
+
 @dir /core
 @brief core: main loop and onion routing functionality
 
@@ -6,13 +8,11 @@ client and relay must implement in order to perform onion routing.
 
 It is divided into three lower-level pieces:
 
-   - \refdir{core/crypto} -- Tor-specific cryptography.
-
-   - \refdir{core/proto} -- Protocol encoding/decoding.
-
-   - \refdir{core/mainloop} -- A connection-oriented asynchronous mainloop.
+ - **\refdir{core/crypto}** -- Tor-specific cryptography.
+ - **\refdir{core/proto}** -- Protocol encoding/decoding.
+ - **\refdir{core/mainloop}** -- A connection-oriented asynchronous mainloop.
 
 and one high-level piece:
 
-   - \refdir{core/or} -- Implements onion routing itself.
+ - **\refdir{core/or}** -- Implements onion routing itself.
 

src/ext/ext.md → src/ext/README.md

@@ -1,3 +1,5 @@
+# src/ext files
+
 @dir /ext
 @brief Externally maintained code
 
@@ -8,30 +10,30 @@ it along with Tor.
 In general, you should not edit this code: we are not the maintainers.
 Instead, you should submit patches upstream.
 
-OpenBSD_malloc_Linux.c:
+### OpenBSD_malloc_Linux.c:
 
 > The OpenBSD malloc implementation, ported to Linux.  Used only when
 > --enable-openbsd-malloc is passed to the configure script.
 
-strlcat.c
-strlcpy.c
+### strlcat.c
+### strlcpy.c
 
 > Implementations of strlcat and strlcpy, the more sane replacements
 > for strcat and strcpy.  These are nonstandard, and some libc
 > implementations refuse to add them for religious reasons.
 
-ht.h
+### ht.h
 
 > An implementation of a hash table in the style of Niels Provos's
 > tree.h.  Shared with Libevent.
 
-tinytest.c tinytest.h
-tinytest_demos.c
-tinytest_macros.h
+### tinytest.c tinytest.h
+### tinytest_demos.c
+### tinytest_macros.h
 
 > A unit testing framework. https://github.com/nmathewson/tinytest
 
-tor_queue.h
+### tor_queue.h
 
 > A copy of sys/queue.h from OpenBSD.  We keep our own copy rather
 > than using sys/queue.h, since some platforms don't have a
@@ -40,47 +42,47 @@ tor_queue.h
 > the identifiers with a TOR_ prefix to avoid conflicts with
 > the system headers.
 
-curve25519_donna/*.c
+### curve25519_donna/*.c
 
 > A copy of Adam Langley's curve25519-donna mostly-portable
 > implementations of curve25519.
 
-csiphash.c
-siphash.h
+### csiphash.c
+### siphash.h
 
 > Marek Majkowski's implementation of siphash 2-4, a secure keyed
 > hash algorithm to avoid collision-based DoS attacks against hash
 > tables.
 
-trunnel/*.[ch]
+### trunnel/*.[ch]
 
 > Headers and runtime code for Trunnel, a system for generating
 > code to encode and decode binary formats.
 
-ed25519/ref10/*
+### ed25519/ref10/*
 
 > Daniel Bernsten's portable ref10 implementation of ed25519.
 > Public domain.
 
-ed25519/donna/*
+### ed25519/donna/*
 
 > Andrew Moon's semi-portable ed25519-donna implementation of
 > ed25519. Public domain.
 
-keccak-tiny/
+### keccak-tiny/
 
 > David Leon Gil's portable Keccak implementation. CC0.
 
-readpassphrase.[ch]
+### readpassphrase.[ch]
 
 > Portable readpassphrase implementation from OpenSSH portable, version
 > 6.8p1.
 
-timeouts/
+### timeouts/
 
 > William Ahern's hierarchical timer-wheel implementation. MIT license.
 
-mulodi/
+### mulodi/
 
 > Contains an overflow-checking 64-bit signed integer multiply
 > from LLVM's compiler_rt.  For some reason, this is missing from

src/feature/README.md

@@ -0,0 +1,32 @@
+# src/feature files
+
+@dir /feature
+@brief feature: domain-specific modules
+
+The "feature" directory has modules that Tor uses only for a particular
+role or service, such as maintaining/using an onion service, operating as a
+relay or a client, or being a directory authority.
+
+Current subdirectories are:
+
+ - **\refdir{feature/api}** -- Support for making Tor embeddable
+ - **\refdir{feature/client}** -- Functionality which only Tor clients need
+ - **\refdir{feature/control}** -- Controller implementation
+ - **\refdir{feature/dirauth}** -- Directory authority
+ - **\refdir{feature/dircache}** -- Directory cache
+ - **\refdir{feature/dirclient}** -- Directory client
+ - **\refdir{feature/dircommon}** -- Shared code between the other directory modules
+ - **\refdir{feature/dirparse}** -- Directory parsing code.
+ - **\refdir{feature/hibernate}** -- Hibernating when Tor is out of bandwidth
+or shutting down
+ - **\refdir{feature/hs}** -- v3 onion service implementation
+ - **\refdir{feature/hs_common}** -- shared code between both onion service
+implementations
+ - **\refdir{feature/keymgt}** -- shared code for key management between
+relays and onion services. 
+ - **\refdir{feature/nodelist}** -- storing and accessing the list of relays on
+the network. 
+ - **\refdir{feature/relay}** -- code that only relay servers and exit servers
+need.
+ - \refdir{feature/rend}** -- v2 onion service implementation
+ - **\refdir{feature/stats}** -- statistics and history