From c6fc64da2b9ab1be9cc809b0d455d35998cde45a Mon Sep 17 00:00:00 2001 From: Sergey Matveev Date: Fri, 13 Jan 2017 13:58:02 +0300 Subject: [PATCH] Better text style --- doc/cfg.texi | 6 ++--- doc/cmds.texi | 64 +++++++++++++++++++++++----------------------- doc/log.texi | 8 +++--- doc/niceness.texi | 2 +- doc/pkt.texi | 6 ++--- doc/platforms.texi | 2 +- doc/sp.texi | 16 ++++++------ doc/spool.texi | 18 ++++++------- doc/usecases.texi | 36 +++++++++++++------------- 9 files changed, 79 insertions(+), 79 deletions(-) diff --git a/doc/cfg.texi b/doc/cfg.texi index 9f2ff3c..4141aba 100644 --- a/doc/cfg.texi +++ b/doc/cfg.texi @@ -91,13 +91,13 @@ transmission. May be omitted to forbid freqing from that node. @item via An array of node identifiers that will be used as a relay to that node. -For example @code{[foo,bar]} means that packet can reach current node by -transitioning through @code{foo} and then @code{bar} nodes. May be +For example @verb{|[foo,bar]|} means that packet can reach current node +by transitioning through @emph{foo} and then @emph{bar} nodes. May be omitted if direct connection exists and no relaying is required. @item addrs Dictionary containing known network addresses of the node. Each key is -human-readable name of the link/address. Values are @code{addr:port} +human-readable name of the link/address. Values are @verb{|addr:port|} pairs pointing to @ref{nncp-daemon}'s listening instance. May be omitted if either no direct connection exists, or @ref{nncp-call} is used with forced address specifying. diff --git a/doc/cmds.texi b/doc/cmds.texi index 04eb205..e3c1fd2 100644 --- a/doc/cmds.texi +++ b/doc/cmds.texi @@ -3,9 +3,9 @@ Nearly all commands have the following common options: -@table @code +@table @option @item -cfg - Path to configuration file. May be overrided by @code{NNCPCFG} + Path to configuration file. May be overrided by @env{NNCPCFG} environment variable. @item -debug Print debug messages. Normally this option should not be used. @@ -33,29 +33,29 @@ Nearly all commands have the following common options: % nncp-call [options] [-rx|-tx] NODE[:ADDR] [FORCEADDR] @end verbatim -Call (connect to) specified @code{NODE} and run @ref{Sync, +Call (connect to) specified @option{NODE} and run @ref{Sync, synchronization} protocol with the @ref{nncp-daemon, daemon} on the remote side. Normally this command could be run any time you wish to either check for incoming packets, or to send out queued ones. Synchronization protocol allows resuming and bidirectional packets transfer. -If @code{-rx} option is specified then only inbound packets transmission -is performed. If @code{-tx} option is specified, then only outbound +If @option{-rx} option is specified then only inbound packets transmission +is performed. If @option{-tx} option is specified, then only outbound transmission is performed. -Each @code{NODE} can contain several uniquely identified -@code{ADDR}esses in @ref{Configuration, configuration} file. If you do +Each @option{NODE} can contain several uniquely identified +@option{ADDR}esses in @ref{Configuration, configuration} file. If you do not specify the exact one, then all will be tried until the first -success. Optionally you can force @code{FORCEADDR} address usage, +success. Optionally you can force @option{FORCEADDR} address usage, instead of addresses taken from configuration file. Pay attention that this command run integrity check for each completely received packet in the background. This can be time consuming and connection could be lost during that check time and remote node won't be notified that file is done. But after successful integrity check that -file will be renamed from @code{.part} one and when you rerun -@code{nncp-call} again, remote node will receive completion at once. +file will be renamed from @file{.part} one and when you rerun +@command{nncp-call} again, remote node will receive completion at once. @node nncp-check @section nncp-check @@ -81,9 +81,9 @@ Start listening TCP daemon, wait for incoming connections and run @ref{nncp-toss} utility in background to process inbound packets from time to time. -@code{-maxconn} option specifies how many simultaneous clients daemon -can handle. @code{-bind} option specifies @code{addr:port} it must bind -to and listen. +@option{-maxconn} option specifies how many simultaneous clients daemon +can handle. @option{-bind} option specifies @option{addr:port} it must +bind to and listen. @node nncp-file @section nncp-file @@ -92,7 +92,7 @@ to and listen. % nncp-file [options] SRC NODE:[DST] @end verbatim -Send @code{SRC} file to remote @code{NODE}. @code{DST} specifies +Send @file{SRC} file to remote @option{NODE}. @file{DST} specifies destination file name in remote's @ref{Configuration, incoming} directory. If this file already exists there, then counter will be appended to it. @@ -112,9 +112,9 @@ file receiving. % nncp-freq [options] NODE:SRC DST @end verbatim -Send file request to @code{NODE}, asking it to send its @code{SRC} file -from @ref{Configuration, freq} directory to our node under @code{DST} -filename in our @ref{Configuration, incoming} one. +Send file request to @option{NODE}, asking it to send its @file{SRC} +file from @ref{Configuration, freq} directory to our node under +@file{DST} filename in our @ref{Configuration, incoming} one. If @ref{Configuration, notification} is enabled on the remote side for file request, then it will sent simple letter after successful file @@ -136,10 +136,10 @@ Parse @ref{Log, log} file and print out its records in human-readable form. % nncp-mail [options] NODE USER ... @end verbatim -Send mail, that is read from stdin, to @code{NODE} and specified -@code{USER}s. Mail message will be compressed. After receiving, remote +Send mail, that is read from stdin, to @option{NODE} and specified +@option{USER}s. Mail message will be compressed. After receiving, remote side will execute specified @ref{Configuration, sendmail} command with -@code{USER}s appended as a command line argument and feed decompressed +@option{USER}s appended as a command line argument and feed decompressed mail body to that command's stdin. @node nncp-newnode @@ -174,10 +174,10 @@ Sender: 2WHBV3TPZHDOZGUJEH563ZEK7M33J4UESRFO4PDKWD5KZNPROABQ Payload size: 4.0 MiB (4162852 bytes) @end verbatim -If you specify @code{-dump} option and provide an @ref{Encrypted, +If you specify @option{-dump} option and provide an @ref{Encrypted, encrypted} packet, then it will verify and decrypt it to stdout. Encrypted packets contain @ref{Plain, plain} ones, that also can be fed -to @code{nncp-pkt}: +to @command{nncp-pkt}: @verbatim Packet type: plain @@ -189,7 +189,7 @@ Payload type: mail Path: stargrave@stargrave.org @end verbatim -And with the @code{-dump} option it will give you the actual payload +And with the @option{-dump} option it will give you the actual payload (the whole file, mail message, and so on). @node nncp-stat @@ -216,7 +216,7 @@ that decrypts all packets and processes all payload packets in them: copies files, sends mails, sends out file requests and relays transition packets. It should be run after each online/offline exchange. -@code{-dryrun} option does not perform any writing and sending, just +@option{-dryrun} option does not perform any writing and sending, just tells what it will do. @node nncp-xfer @@ -226,21 +226,21 @@ tells what it will do. % nncp-xfer [options] [-force] [-keep] [-rx|-tx] DIR @end verbatim -Search for directory in @code{DIR} containing inbound packets for us and +Search for directory in @file{DIR} containing inbound packets for us and move them to local @ref{Spool, spool} directory. Also search for known neighbours directories and move locally queued outbound packets to them. This command is used for offline packets transmission. -If @code{-force} option is specified, then outbound neighbour(s) +If @option{-force} option is specified, then outbound neighbour(s) directories will be created. This is useful for the first time usage, when storage device does not have any directories tree. -If @code{-keep} option is specified, then keep copied files, do not +If @option{-keep} option is specified, then keep copied files, do not remove them. -@code{-rx} option tells only to move inbound packets addressed to us. -@code{-tx} option tells exactly the opposite: move only outbound packets. +@option{-rx} option tells only to move inbound packets addressed to us. +@option{-tx} option tells exactly the opposite: move only outbound packets. -@code{DIR} directory has the following structure: -@code{RECIPIENT/SENDER/PACKET}, where @code{RECIPIENT} is Base32 encoded -destination node, @code{SENDER} is Base32 encoded sender node. +@file{DIR} directory has the following structure: +@file{RECIPIENT/SENDER/PACKET}, where @file{RECIPIENT} is Base32 encoded +destination node, @file{SENDER} is Base32 encoded sender node. diff --git a/doc/log.texi b/doc/log.texi index 2eaeef3..1b0f43e 100644 --- a/doc/log.texi +++ b/doc/log.texi @@ -19,14 +19,14 @@ I 2017-01-09T08:42:18.990005394Z [sp-infos node="BYRRQUULEHINPKEFN7CHMSHR5I5CK7P I 2017-01-09T08:48:59.264847401Z [call-finish duration="10" node="BYRRQUULEHINPKEFN7CHMSHR5I5CK7PMX5HQNCYERTBAR4BOCG6Q" rxbytes="60" rxspeed="60" txbytes="108" txspeed="108"] @end verbatim -@table @code +@table @emph @item | Space character. @item LEVEL - Is single character log level. As a rule is is either @code{I} - (informational message), or @code{E} (error message). + Is single character log level. As a rule is is either @verb{|I|} + (informational message), or @verb{|E|} (error message). @item DATETIME - UTC datetime in RFC 3339 @code{2006-01-02T15:04:05.999999999Z} format. + UTC datetime in RFC 3339 @verb{|2006-01-02T15:04:05.999999999Z|} format. @item SD Structured data as in RFC 5424. @item MSG diff --git a/doc/niceness.texi b/doc/niceness.texi index 4b659d0..50f392b 100644 --- a/doc/niceness.texi +++ b/doc/niceness.texi @@ -1,7 +1,7 @@ @node Niceness @unnumbered Niceness -Each transmitted packet has niceness level, as Unix has @code{nice} +Each transmitted packet has niceness level, as Unix has @command{nice} command for controlling processes priority. Higher nicer level means that packet is "nicer" and allows other to bypass him -- that means lower transmission precedence. diff --git a/doc/pkt.texi b/doc/pkt.texi index c2a4301..35700c1 100644 --- a/doc/pkt.texi +++ b/doc/pkt.texi @@ -29,7 +29,7 @@ drive. @headitem @tab XDR type @tab Value @item Magic number @tab 8-byte, fixed length opaque data @tab - @code{NNCPP0x00x00x01} + @verb{|NNCPP0x00x00x01|} @item Payload type @tab unsigned integer @tab 0 (file), 1 (freq), 2 (mail), 3 (transition) @@ -84,7 +84,7 @@ Each encrypted packet has the following header: @headitem @tab XDR type @tab Value @item Magic number @tab 8-byte, fixed length opaque data @tab - @code{NNCPE0x00x00x01} + @verb{|NNCPE0x00x00x01|} @item Niceness @tab unsigned integer @tab 1-255, packet @ref{Niceness, niceness} level @@ -123,7 +123,7 @@ After the headers comes an encrypted payload size and MAC of that size. @headitem @tab XDR type @tab Value @item Size @tab unsigned hyper integer @tab - @code{NNCPE0x00x00x01} + @verb{|NNCPE0x00x00x01|} Payload size. @end multitable diff --git a/doc/platforms.texi b/doc/platforms.texi index 56a7412..5a259e3 100644 --- a/doc/platforms.texi +++ b/doc/platforms.texi @@ -12,7 +12,7 @@ % make -C nncp-0.1 all @end verbatim -There is @code{install} target respecting @env{DESTDIR}. It will +There is @command{install} target respecting @env{DESTDIR}. It will install binaries and info-documentation. @node FreeBSD diff --git a/doc/sp.texi b/doc/sp.texi index 42a4766..ab8390e 100644 --- a/doc/sp.texi +++ b/doc/sp.texi @@ -14,7 +14,7 @@ unacceptable performance degradation. SP works on top of @url{http://noiseprotocol.org/noise.html#interactive-patterns, -@code{Noise_IK_25519_ChaChaPoly_BLAKE2b}} protocol. Each Noise packet +@verb{|Noise_IK_25519_ChaChaPoly_BLAKE2b|}} protocol. Each Noise packet are sent inside XDR envelope: @verbatim @@ -27,31 +27,31 @@ are sent inside XDR envelope: @headitem @tab XDR type @tab Value @item Magic number @tab 8-byte, fixed length opaque data @tab - @code{NNCPS0x00x00x01} + @verb{|NNCPS0x00x00x01|} @item Payload @tab variable length opaque data @tab Noise packet itself @end multitable -Peers static keys are specified as @ref{Configuration, @code{noisepub}} +Peers static keys are specified as @ref{Configuration, @emph{noisepub}} configuration entry. -Payload inside Noise packets has maximum size of @code{65 KiB - 256 B = +Payload inside Noise packets has maximum size of @emph{65 KiB - 256 B = 65280 B}. It is sent immediately in the first message by each side. The very first payload (that is carried inside handshake messages) is always -padded to the maximum size with @code{HALT} packets (read below), for -hiding actual number of @code{INFO} packets (number of files available +padded to the maximum size with @emph{HALT} packets (read below), for +hiding actual number of @emph{INFO} packets (number of files available for transmission). Each SP payload is a concatenation of SP packets. Each packet has XDR-encoded header and then corresponding XDR-encoded body. Header is just an unsigned integer telling what body structure follows. -@table @code +@table @emph @item HALT Stop file transmission, empty sending queue on the remote side. - Actually @code{HALT} packet does not have any body, only the header + Actually @emph{HALT} packet does not have any body, only the header with the type. It is also used in the first payload for padding to the maximum size. @verbatim diff --git a/doc/spool.texi b/doc/spool.texi index 097b180..53ea301 100644 --- a/doc/spool.texi +++ b/doc/spool.texi @@ -17,18 +17,18 @@ spool/BYRR...CG6Q/tx/NSYY...ZUU6 spool/BYRR...CG6Q/tx/ZI5U...5RRQ @end verbatim -Except for @code{tmp}, all other directories are Base32-encoded node -identifiers (@code{2WHB...OABQ}, @code{BYRR...CG6Q} in our example). -Each node subdirectory has @code{rx} (received, partly received and -currently unprocessed packets) and @code{tx} (for outbound packets) +Except for @file{tmp}, all other directories are Base32-encoded node +identifiers (@file{2WHB...OABQ}, @file{BYRR...CG6Q} in our example). +Each node subdirectory has @file{rx} (received, partly received and +currently unprocessed packets) and @file{tx} (for outbound packets) directories. -Each @code{rx}/@code{tx} directory contains one file per encrypted +Each @file{rx}/@file{tx} directory contains one file per encrypted packet. Its filename is Base32 encoded BLAKE2b hash of the contents. So -it can be integrity checked at any time. @code{5ZIB...UMKW.part} is -partly received file from @code{2WHB...OABQ} node. @code{tx} directory +it can be integrity checked at any time. @file{5ZIB...UMKW.part} is +partly received file from @file{2WHB...OABQ} node. @file{tx} directory can not contain partly written files -- they are moved atomically from -@code{tmp}. +@file{tmp}. -Only one process can work with @code{rx}/@code{tx} directories at once, +Only one process can work with @file{rx}/@file{tx} directories at once, so there are corresponding lock files. diff --git a/doc/usecases.texi b/doc/usecases.texi index f6a2be3..7492c37 100644 --- a/doc/usecases.texi +++ b/doc/usecases.texi @@ -35,7 +35,7 @@ email as a mail via NNCP to specified node. This is done similarly as with UUCP and as written in Postfix @url{http://www.postfix.org/UUCP_README.html, documentation}. -Search for @code{uucp} related strings in @code{master.cf} and replace +Search for @verb{|uucp|} related strings in @file{master.cf} and replace command to NNCP ones: @verbatim @@ -43,14 +43,14 @@ nncp unix - n n - - pipe flags=Fqhu user=nncp argv=nncp-mail -quiet $nexthop $re @end verbatim then add transport map, telling that mail for example.com domain can be -reached through NNCP transport to node @code{bob}: +reached through NNCP transport to node @emph{bob}: @verbatim example.com nncp:bob @end verbatim Now, all mail will be stored in NNCP @ref{Spool, spool}, that after -exchanging and tossing will call local @code{sendmail} command to +exchanging and tossing will call local @command{sendmail} command to deliver them just that was happened on the same machine. @node UsecaseUnreliable @@ -73,7 +73,7 @@ The command below: % nncp-file another_file bob:movie.avi @end verbatim -will queue two files for sending to @code{bob} node. Fire and forget! +will queue two files for sending to @code{emph} node. Fire and forget! Now this is daemon's job (or offline transfer) to send this file part by part to remote system when it is available. @@ -105,20 +105,20 @@ This is some kind of too slow link. Offline delivery methods is the only choice. Just send files as shown in previous section, but use removable media for transferring packets to other nodes. -Assume that you send two files to @code{bob} node. Insert USB storage +Assume that you send two files to @emph{bob} node. Insert USB storage device, mount it and run: @verbatim % nncp-xfer -node bob /media/usbstick @end verbatim -to copy all outbound packets related to @code{bob}'s node. Use -@code{-force} option to forcefully create related directory on USB +to copy all outbound packets related to @emph{bob}'s node. Use +@option{-force} option to forcefully create related directory on USB storage if they are missing (for example when running for the first time). -If you use single storage device to transfer data both to @code{bob} and -@code{alice}, then just omit @code{-node} option to copy all existing +If you use single storage device to transfer data both to @emph{bob} and +@emph{alice}, then just omit @option{-node} option to copy all existing outgoing packets to that storage device. @verbatim @@ -133,7 +133,7 @@ it in their computers, they will use exactly the same command: @end verbatim to find all packets related to their node and copy them locally for -further processing. @code{nncp-xfer} is the only command used with +further processing. @ref{nncp-xfer} is the only command used with removable devices. @node UsecaseF2F @@ -173,7 +173,7 @@ connections. @verbatim % nncp-call bob @end verbatim -will try to connect to @code{bob}'s node known TCP addresses (taken from +will try to connect to @emph{bob}'s node known TCP addresses (taken from configuration file) and send all related outbound packets and retrieve those the Bob has. All interrupted transfers will be automatically resumed. @@ -206,17 +206,17 @@ neigh: @end verbatim That configuration file tells that we have got two known neighbours: -@code{bob} and @code{bob-airgap}. @code{bob} can be reached via online -connection using @code{lan} address. @code{bob-airgap} can be reached by -sending intermediate relay packet through the @code{bob}. +@emph{bob} and @emph{bob-airgap}. @emph{bob} can be reached via online +connection using @emph{lan} address. @emph{bob-airgap} can be reached by +sending intermediate relay packet through the @emph{bob}. -Any command like @code{nncp-file myfile bob-airgap:} will automatically -create an encapsulated packet: one for the destination endpoint, and -other carrying it for intermediate relaying node. +Any command like @command{nncp-file myfile bob-airgap:} will +automatically create an encapsulated packet: one for the destination +endpoint, and other carrying it for intermediate relaying node. Pay attention that relaying node knows nothing about the packet inside, but just its size and priority. Transition packets are encrypted too. -@code{bob} can not read @code{bob-airgap}'s packets. +@emph{bob} can not read @emph{bob-airgap}'s packets. @node UsecaseCensor @section Network censorship bypassing -- 2.44.0