improve documentation

- add example to README to extract gitweb.owner from a git config.
  this is used in gitweb and some cgit configurations.
- fix (new) mandoc warnings (new sentence on each line).
- improve some texts in the man pages, sort / structure some list items.

README

@@ -61,6 +61,23 @@ make
 make install
 
 
+Extract owner field from git config
+-----------------------------------
+
+A (hacky) way to extract the gitweb owner for example in the format:
+
+	[gitweb]
+		owner = Name here
+
+Script:
+
+	#!/bin/sh
+	awk '/^[ 	]*owner[ 	]=/ {
+		sub(/^[^=]*=[ 	]*/, "");
+		print $0;
+	}'
+
+
 Features
 --------
 
@@ -86,7 +103,7 @@ Cons
 - Not suitable for repositories with many branches, a quite linear history is
   assumed (from HEAD).
 - Relatively slow to run the first time (about 3 seconds for sbase,
-  1500+ commits), incremental updates after it are faster.
+  1500+ commits), incremental updates are faster.
 - Does not support some of the dynamic features cgit has, like:
   - snapshot tarballs.
   - file tree per commit.

stagit-index.1

@@ -10,13 +10,14 @@
 .Sh DESCRIPTION
 .Nm
 will create an index HTML page for the repositories specified and writes
-the HTML data to stdout. The repos in the index are in the same order as
+the HTML data to stdout.
-the arguments
+The repos in the index are in the same order as the arguments
 .Ar repodir
 specified.
 .Pp
-The basename of the directory is used as the name. The suffix ".git" is
+The basename of the directory is used as the repository name.
-removed from the basename, this is commonly used for "bare" repos.
+The suffix ".git" is removed from the basename, this suffix is commonly used
+for "bare" repos.
 .Pp
 The content of the follow files specifies the meta data for each repository:
 .Bl -tag -width Ds
@@ -28,10 +29,10 @@ owner of repository
 .Pp
 For changing the style of the page you can use the following files:
 .Bl -tag -width Ds
-.It logo.png
-32x32 logo.
 .It favicon.png
 favicon image.
+.It logo.png
+32x32 logo.
 .It style.css
 CSS stylesheet.
 .El

stagit.1

@@ -14,51 +14,58 @@ writes HTML pages for the repository
 .Ar repodir
 to the current directory.
 .Pp
-Optionally the
+The options are as follows:
-.Fl c Ar cachefile
+.Bl -tag -width Ds
-option can be used to cache the entries of the log page up to the point of
+.It Fl c Ar cachefile
-the last commit. The
+Cache the entries of the log page up to the point of
+the last commit.
+The
 .Ar cachefile
-will store the last commit id and the entries in the HTML table. It is up
+will store the last commit id and the entries in the HTML table.
-to the user to make sure the state of the
+It is up to the user to make sure the state of the
 .Ar cachefile
 is in sync with the history of the repository.
+.El
 .Pp
 The following files will be written:
 .Bl -tag -width Ds
 .It atom.xml
 Atom XML feed
 .It files.html
-List of files in the latest HEAD commit, linking to the file.
+List of files in the latest tree, linking to the file.
 .It log.html
 List of commits in order of most recent to old of the commits (top to bottom),
-each commit links to a page with a diff and diffstat of the commit.
+each commit links to a page with a diffstat and diff of the commit.
 .It refs.html
 Lists references of the repository such as branches and tags.
 .El
 .Pp
 For each entry in HEAD a file will be written in the format:
-file/filepath.html. This file will contain the textual data of the file
+file/filepath.html.
-prefixed by line numbers. The file will have the string "Binary file"
+This file will contain the textual data of the file prefixed by line numbers.
-if the data is considered to be non-textual.
+The file will have the string "Binary file" if the data is considered to be
+non-textual.
 .Pp
 For each commit a file will be written in the format:
-commit/commitid.html. This file will contain the diff and diffstat of the
+commit/commitid.html.
-commit. It will write the string "Binary files differ" if the data is
+This file will contain the diffstat and diff of the commit.
-considered to be non-textual. Too large diffs will be suppressed and a string
+It will write the string "Binary files differ" if the data is considered to
+be non-textual.
+Too large diffs will be suppressed and a string
 "Diff is too large, output suppressed" will be written.
 .Pp
 When a commit HTML file exists it won't be overwritten again, note that if
 you've changed
 .Nm
 or changed one of the metadata files of the repository it is recommended to
-recreate all the output files because it will contain old data. To do this
+recreate all the output files because it will contain old data.
-remove the output directory and
+To do this remove the output directory and
 .Ar cachefile ,
 then recreate the files.
 .Pp
-The basename of the directory is used as the name. The suffix ".git" is
+The basename of the directory is used as the repository name.
-removed from the basename, this is commonly used for "bare" repos.
+The suffix ".git" is removed from the basename, this suffix is commonly used
+for "bare" repos.
 .Pp
 The content of the follow files specifies the metadata for each repository:
 .Bl -tag -width Ds
@@ -75,10 +82,10 @@ exists in HEAD a direct link in the menu is made.
 .Pp
 For changing the style of the page you can use the following files:
 .Bl -tag -width Ds
-.It logo.png
-32x32 logo.
 .It favicon.png
 favicon image.
+.It logo.png
+32x32 logo.
 .It style.css
 CSS stylesheet.
 .El