Merge branch 'master' of ssh://git-annex.branchable.com

3 files changed, 105 insertions, 0 deletions

diff --git a/doc/todo/cleaner_hack_for_man_pages.mdwn b/doc/todo/cleaner_hack_for_man_pages.mdwn
new file mode 100644
index 000000000..d54b3fc2a
--- /dev/null
+++ b/doc/todo/cleaner_hack_for_man_pages.mdwn
@@ -0,0 +1,75 @@
+In recent history, we have realized that the small Perl script that
+generates the man pages from Markdown is fairly limited.
+
+Two approaches have been considered:
+
+* go-md2man
+* pandoc
+
+Here is how pandoc does it:
+
+    $ pandoc -f markdown -t man doc/git-annex-shell.mdwn | pastebinit
+    http://paste.debian.net/424341/
+
+Both initially fail at setting a proper `.TH` line on top, but
+otherwise seem to work more or less correctly. --[[anarcat]]
+
+Okay, update: the above commandline was incorrect for some reason. The
+proper incantation is:
+
+    pandoc -s -t man doc/git-annex-shell.mdwn -o git-annex-shell.1
+
+For example:
+
+    $ pandoc -s -t man doc/git-annex-shell.mdwn | man -l - | pastebinit
+    http://paste.debian.net/430630/
+
+So by default, there is no title or section header, which is, if you
+ask me a little stupid: pandoc could guess a little better and parse
+the `.SH NAME` section.
+
+The workaround for this is to add Pandoc metadata either to the file,
+for example:
+
+[[!format diff """
+diff --git a/doc/git-annex-shell.mdwn b/doc/git-annex-shell.mdwn
+index 9b3d126..13f64ae 100644
+--- a/doc/git-annex-shell.mdwn
++++ b/doc/git-annex-shell.mdwn
+@@ -1,3 +1,6 @@
++% git-annex-shell(1) Git-annex manual | Version 5
++% Joey Hess
++
+ # NAME
+ 
+ git-annex-shell - Restricted login shell for git-annex only SSH access
+"""]]
+
+But Ikiwiki is likely to barf on such comments, so it's probably
+preferable to pass those parameters at build time:
+
+    $ pandoc -s -V title="git-annex-shell" -V section=1 -t man doc/git-annex-shell.mdwn  | man -l - | pastebinit
+    http://paste.debian.net/430632/
+
+Looks better already! But we can improve on that even more!
+
+    $ pandoc -s -V title="git-annex-shell" -V section=1 \
+        -V header="Git Annex manual" -V footer="Version 5.xxx" \
+        -t man doc/git-annex-shell.mdwn  | man -l - | pastebinit
+    http://paste.debian.net/430633/
+
+Much better. And the version can probably be passed in from the build
+system (or that footer can just be dropped).
+
+So a more complete patch would involve fixing the build system to use
+(and depend on!) pandoc then remove the pesky warnings at the bottom
+of all Markdown files.
+
+More investigation would probably be necessary to check the resulting
+man pages for syntax errors. For example, the above rendering, in the
+`SEE ALSO` section, has `[git-annex] (1)` instead of
+`git-annex(1)`, since Pandoc doesn't know about ikiwiki links. Maybe
+some pre-processing would be necessary there? :/ It sure is useful to
+have those links working in the web version!
+
+I hope that helps regardless.
diff --git a/doc/todo/dumb__44___unsafe__44___human-readable_backend/comment_3_d46183e53b1e6293681efadec9b46c6b._comment b/doc/todo/dumb__44___unsafe__44___human-readable_backend/comment_3_d46183e53b1e6293681efadec9b46c6b._comment
new file mode 100644
index 000000000..b21e9e21d
--- /dev/null
+++ b/doc/todo/dumb__44___unsafe__44___human-readable_backend/comment_3_d46183e53b1e6293681efadec9b46c6b._comment
@@ -0,0 +1,18 @@
+[[!comment format=mdwn
+ username="anarcat"
+ subject="""comment 3"""
+ date="2016-04-09T04:39:11Z"
+ content="""
+What about having a direct more in an external work tree?
+
+I could have my .git directory in some local directory (say
+`~/.git-annex/remote-mp3.git`) and the actual files on the device (say
+`/media/anarcat/mounted/mp3`).
+
+I know that there are many possible names for a single key, but isn't
+that a problem for direct mode as well?
+
+And I know it's a poney... I keep on asking for poneys here, but
+poneys are great, and actually quite useful and even friendly animals
+if you can use and take care of them correctly. :)
+"""]]
diff --git a/doc/todo/wishlist__58___spec.remotes_for_other_peer_network_data_stores___40__gnunet__44___freenet__41__/comment_4_469c952a131d2aac45615afb3a69d10c._comment b/doc/todo/wishlist__58___spec.remotes_for_other_peer_network_data_stores___40__gnunet__44___freenet__41__/comment_4_469c952a131d2aac45615afb3a69d10c._comment
new file mode 100644
index 000000000..4fd2ddc21
--- /dev/null
+++ b/doc/todo/wishlist__58___spec.remotes_for_other_peer_network_data_stores___40__gnunet__44___freenet__41__/comment_4_469c952a131d2aac45615afb3a69d10c._comment
@@ -0,0 +1,12 @@
+[[!comment format=mdwn
+ username="0xloem@0bd8a79a57e4f0dcade8fc81d162c37eae4d6730"
+ nickname="0xloem"
+ subject="freenet special remote"
+ date="2016-04-09T10:37:22Z"
+ content="""
+I've gotten derailed, but in case somebody else is interested for now, I've started a freenet special remote at https://github.com/xloem/gitlakepy .  Also includes beginnings of a generic python class for special remotes in the same scriptfile.
+
+SETSTATE is helpful but doesn't allow for any form of hashing the file offline, to ensure the hash matches.  It means there could be data corruption uploading the file and there would be no way to check that the hash matched the local data.  It would be nice to provide new hashing backends as well, perhaps then somebody could make a multi-hash which stores different hashes side-by-side to resolve such paranoia.
+
+I guess for now the right way to do these things is to add the new capabilities straight to the internals of git-annex, but learning haskell is an adventure when time is a constraint.
+"""]]