From 73aedc7877b9e312184b250d5ce56012a90aa1d4 Mon Sep 17 00:00:00 2001 From: Gabriel Filion Date: Mon, 1 Oct 2012 03:13:53 -0400 Subject: [PATCH] Documentation: Protect file extensions from start of line. In the documentation files, we use file extensions as words to simplify the text. When compiling man pages from the Markdown files, it is possible that an extension lands at the beginning of a line. In such a case, the extension is mistakenly identified as a Groff macro. It seems as though Groff simply ignores it since it is not a known macro, but emits a warning about the syntax. This was caught thanks to the debian package's lintian output at: http://lintian.debian.org/maintainer/jmtd@debian.org.html#bup Since we're putting highlighting on file extensions, we should add it to all cases, even though there's not risk of it landing at the beginning of a line. This way, the documentation looks better standardized. Signed-off-by: Gabriel Filion Reviewed-by: Rob Browning --- Documentation/bup-bloom.md | 8 ++++---- Documentation/bup-margin.md | 2 +- Documentation/bup-midx.md | 32 ++++++++++++++++---------------- Documentation/bup-server.md | 2 +- 4 files changed, 22 insertions(+), 22 deletions(-) diff --git a/Documentation/bup-bloom.md b/Documentation/bup-bloom.md index f50e07d..9efea60 100644 --- a/Documentation/bup-bloom.md +++ b/Documentation/bup-bloom.md @@ -29,7 +29,7 @@ updates or regenerates it as needed. one from scratch. -d, \--dir=*directory* -: the directory, containing .idx files, to process. +: the directory, containing `.idx` files, to process. Defaults to $BUP_DIR/objects/pack -o, \--outfile=*outfile* @@ -43,10 +43,10 @@ updates or regenerates it as needed. -c, \--check=*idxfile* : checks the bloom file (counterintuitively outfile) - against the specified .idx file, first checks that the - bloom filter is claiming to contain the .idx, then + against the specified `.idx` file, first checks that the + bloom filter is claiming to contain the `.idx`, then checks that it does actually contain all of the objects - in the .idx. Does not write anything and ignores the + in the `.idx`. Does not write anything and ignores the `-k` option. # BUP diff --git a/Documentation/bup-margin.md b/Documentation/bup-margin.md index 23f0ef1..0e5376c 100644 --- a/Documentation/bup-margin.md +++ b/Documentation/bup-margin.md @@ -47,7 +47,7 @@ close to 160 bits. search algorithm. \--ignore-midx -: don't use .midx files, use only .idx files. This is +: don't use `.midx` files, use only `.idx` files. This is only really useful when used with `--predict`. diff --git a/Documentation/bup-midx.md b/Documentation/bup-midx.md index 7c67a2d..a256c6c 100644 --- a/Documentation/bup-midx.md +++ b/Documentation/bup-midx.md @@ -4,7 +4,7 @@ # NAME -bup-midx - create a multi-index (.midx) file from several .idx files +bup-midx - create a multi-index (`.midx`) file from several `.idx` files # SYNOPSIS @@ -12,45 +12,45 @@ bup midx [-o *outfile*] \<-a|-f|*idxnames*...\> # DESCRIPTION -`bup midx` creates a multi-index (.midx) file from one or more -git pack index (.idx) files. +`bup midx` creates a multi-index (`.midx`) file from one or more +git pack index (`.idx`) files. -Note: you should no longer need to run this command by hand. +Note: you should no longer need to run this command by hand. It gets run automatically by `bup-save`(1) and similar commands. # OPTIONS -o, \--output=*filename.midx* -: use the given output filename for the .midx file. +: use the given output filename for the `.midx` file. Default is auto-generated. - + -a, \--auto -: automatically generate new .midx files for any .idx +: automatically generate new `.midx` files for any `.idx` files where it would be appropriate. - + -f, \--force -: force generation of a single new .midx file containing - *all* your .idx files, even if other .midx files +: force generation of a single new `.midx` file containing + *all* your `.idx` files, even if other `.midx` files already exist. This will result in the fastest backup performance, but may take a long time to run. \--dir=*packdir* -: specify the directory containing the .idx/.midx files +: specify the directory containing the `.idx`/`.midx` files to work with. The default is $BUP_DIR/objects/pack and $BUP_DIR/indexcache/*. \--max-files -: maximum number of .idx files to open at a time. You +: maximum number of `.idx` files to open at a time. You can use this if you have an especially small number of file descriptors available, so that midx can complete (though possibly non-optimally) even if it can't open - all your .idx files at once. The default value of this + all your `.idx` files at once. The default value of this option should be fine for most people. \--check -: validate a .midx file by ensuring that all objects in - its contained .idx files exist inside the .midx. May +: validate a `.midx` file by ensuring that all objects in + its contained `.idx` files exist inside the `.midx`. May be useful for debugging. @@ -74,7 +74,7 @@ Normal idx files are convenient because it means you can use files can get slow when you have a lot of very large packs (which git typically doesn't have, but bup often does). -bup .midx files consist of a single sorted list of all the objects +bup `.midx` files consist of a single sorted list of all the objects contained in all the .pack files it references. This list can be binary searched in about log2(m) steps, where m is the total number of objects. diff --git a/Documentation/bup-server.md b/Documentation/bup-server.md index 00c5df0..6f25f4c 100644 --- a/Documentation/bup-server.md +++ b/Documentation/bup-server.md @@ -33,7 +33,7 @@ dumb : In this mode, the server will not check its local index before writing an object. To avoid writing duplicate objects, the server will tell the client to download all - of its .idx files at the start of the session. This + of its `.idx` files at the start of the session. This mode is useful on low powered server hardware (ie router/slow NAS). -- 2.39.2