hg-ssh: copy doc string to man page

This corrects a warning from lintian that we're shipping an executable without
a man page. Since there is a doc string in the text, let's use that for the man
page.

mercurial/help/hg-ssh.8.txt

@@ -0,0 +1,71
+========
+ hg-ssh
+========
+
+----------------------------------------
+restricted ssh login shell for Mercurial
+----------------------------------------
+
+:Author:         Thomas Arendsen Hein <[e-mail]>
+:Organization:   Mercurial
+:Manual section: 8
+:Manual group:   Mercurial Manual
+
+.. contents::
+   :backlinks: top
+   :class: htmlonly
+   :depth: 1
+
+Synopsis
+""""""""
+**hg-ssh** repositories...
+
+Description
+"""""""""""
+**hg-ssh** is a wrapper for ssh access to a limited set of mercurial repos.
+
+To be used in ~/.ssh/authorized_keys with the "command" option, see sshd(8):
+command="hg-ssh path/to/repo1 /path/to/repo2 ~/repo3 ~user/repo4" ssh-dss ...
+(probably together with these other useful options:
+no-port-forwarding,no-X11-forwarding,no-agent-forwarding)
+
+This allows pull/push over ssh from/to the repositories given as arguments.
+
+If all your repositories are subdirectories of a common directory, you can
+allow shorter paths with:
+command="cd path/to/my/repositories && hg-ssh repo1 subdir/repo2"
+
+You can use pattern matching of your normal shell, e.g.:
+command="cd repos && hg-ssh user/thomas/* projects/{mercurial,foo}"
+
+You can also add a --read-only flag to allow read-only access to a key, e.g.:
+command="hg-ssh --read-only repos/\*"
+
+Bugs
+""""
+Probably lots, please post them to the mailing list (see Resources_
+below) when you find them.
+
+See Also
+""""""""
+|hg(1)|_
+
+Author
+""""""
+Written by Matt Mackall <[e-mail]>
+
+Resources
+"""""""""
+Main Web Site: https://mercurial-scm.org/
+
+Source code repository: http://selenic.com/hg
+
+Mailing list: http://selenic.com/mailman/listinfo/mercurial
+
+Copying
+"""""""
+Copyright (C) 2005-2016 Matt Mackall.
+Free use of this software is granted under the terms of the GNU General
+Public License version 2 or any later version.
+
+.. include:: common.txt

doc/gendoc.py

@@ -1,223 +1,224
 #!/usr/bin/env python
 """usage: %s DOC ...
 
 where DOC is the name of a document
 """
 
 from __future__ import absolute_import
 
 import os
 import sys
 import textwrap
 
 # This script is executed during installs and may not have C extensions
 # available. Relax C module requirements.
 os.environ['HGMODULEPOLICY'] = 'allow'
 # import from the live mercurial repo
 sys.path.insert(0, "..")
 from mercurial import demandimport; demandimport.enable()
 from mercurial import (
     commands,
     extensions,
     help,
     minirst,
     ui as uimod,
 )
 from mercurial.i18n import (
     gettext,
     _,
 )
 
 table = commands.table
 globalopts = commands.globalopts
 helptable = help.helptable
 loaddoc = help.loaddoc
 
 def get_desc(docstr):
     if not docstr:
         return "", ""
     # sanitize
     docstr = docstr.strip("\n")
     docstr = docstr.rstrip()
     shortdesc = docstr.splitlines()[0].strip()
 
     i = docstr.find("\n")
     if i != -1:
         desc = docstr[i + 2:]
     else:
         desc = shortdesc
 
     desc = textwrap.dedent(desc)
 
     return (shortdesc, desc)
 
 def get_opts(opts):
     for opt in opts:
         if len(opt) == 5:
             shortopt, longopt, default, desc, optlabel = opt
         else:
             shortopt, longopt, default, desc = opt
             optlabel = _("VALUE")
         allopts = []
         if shortopt:
             allopts.append("-%s" % shortopt)
         if longopt:
             allopts.append("--%s" % longopt)
         if isinstance(default, list):
             allopts[-1] += " <%s[+]>" % optlabel
         elif (default is not None) and not isinstance(default, bool):
             allopts[-1] += " <%s>" % optlabel
         if '\n' in desc:
             # only remove line breaks and indentation
             desc = ' '.join(l.lstrip() for l in desc.split('\n'))
         desc += default and _(" (default: %s)") % default or ""
         yield (", ".join(allopts), desc)
 
 def get_cmd(cmd, cmdtable):
     d = {}
     attr = cmdtable[cmd]
     cmds = cmd.lstrip("^").split("|")
 
     d['cmd'] = cmds[0]
     d['aliases'] = cmd.split("|")[1:]
     d['desc'] = get_desc(gettext(attr[0].__doc__))
     d['opts'] = list(get_opts(attr[1]))
 
     s = 'hg ' + cmds[0]
     if len(attr) > 2:
         if not attr[2].startswith('hg'):
             s += ' ' + attr[2]
         else:
             s = attr[2]
     d['synopsis'] = s.strip()
 
     return d
 
 def showdoc(ui):
     # print options
     ui.write(minirst.section(_("Options")))
     multioccur = False
     for optstr, desc in get_opts(globalopts):
         ui.write("%s\n    %s\n\n" % (optstr, desc))
         if optstr.endswith("[+]>"):
             multioccur = True
     if multioccur:
         ui.write(_("\n[+] marked option can be specified multiple times\n"))
         ui.write("\n")
 
     # print cmds
     ui.write(minirst.section(_("Commands")))
     commandprinter(ui, table, minirst.subsection)
 
     # print help topics
     # The config help topic is included in the hgrc.5 man page.
     helpprinter(ui, helptable, minirst.section, exclude=['config'])
 
     ui.write(minirst.section(_("Extensions")))
     ui.write(_("This section contains help for extensions that are "
                "distributed together with Mercurial. Help for other "
                "extensions is available in the help system."))
     ui.write("\n\n"
              ".. contents::\n"
              "   :class: htmlonly\n"
              "   :local:\n"
              "   :depth: 1\n\n")
 
     for extensionname in sorted(allextensionnames()):
         mod = extensions.load(ui, extensionname, None)
         ui.write(minirst.subsection(extensionname))
         ui.write("%s\n\n" % gettext(mod.__doc__))
         cmdtable = getattr(mod, 'cmdtable', None)
         if cmdtable:
             ui.write(minirst.subsubsection(_('Commands')))
             commandprinter(ui, cmdtable, minirst.subsubsubsection)
 
 def showtopic(ui, topic):
     extrahelptable = [
         (["common"], '', loaddoc('common')),
         (["hg.1"], '', loaddoc('hg.1')),
+        (["hg-ssh.8"], '', loaddoc('hg-ssh.8')),
         (["hgignore.5"], '', loaddoc('hgignore.5')),
         (["hgrc.5"], '', loaddoc('hgrc.5')),
         (["hgignore.5.gendoc"], '', loaddoc('hgignore')),
         (["hgrc.5.gendoc"], '', loaddoc('config')),
     ]
     helpprinter(ui, helptable + extrahelptable, None, include=[topic])
 
 def helpprinter(ui, helptable, sectionfunc, include=[], exclude=[]):
     for names, sec, doc in helptable:
         if exclude and names[0] in exclude:
             continue
         if include and names[0] not in include:
             continue
         for name in names:
             ui.write(".. _%s:\n" % name)
         ui.write("\n")
         if sectionfunc:
             ui.write(sectionfunc(sec))
         if callable(doc):
             doc = doc(ui)
         ui.write(doc)
         ui.write("\n")
 
 def commandprinter(ui, cmdtable, sectionfunc):
     h = {}
     for c, attr in cmdtable.items():
         f = c.split("|")[0]
         f = f.lstrip("^")
         h[f] = c
     cmds = h.keys()
     cmds.sort()
 
     for f in cmds:
         if f.startswith("debug"):
             continue
         d = get_cmd(h[f], cmdtable)
         ui.write(sectionfunc(d['cmd']))
         # short description
         ui.write(d['desc'][0])
         # synopsis
         ui.write("::\n\n")
         synopsislines = d['synopsis'].splitlines()
         for line in synopsislines:
             # some commands (such as rebase) have a multi-line
             # synopsis
             ui.write("   %s\n" % line)
         ui.write('\n')
         # description
         ui.write("%s\n\n" % d['desc'][1])
         # options
         opt_output = list(d['opts'])
         if opt_output:
             opts_len = max([len(line[0]) for line in opt_output])
             ui.write(_("Options:\n\n"))
             multioccur = False
             for optstr, desc in opt_output:
                 if desc:
                     s = "%-*s  %s" % (opts_len, optstr, desc)
                 else:
                     s = optstr
                 ui.write("%s\n" % s)
                 if optstr.endswith("[+]>"):
                     multioccur = True
             if multioccur:
                 ui.write(_("\n[+] marked option can be specified"
                            " multiple times\n"))
             ui.write("\n")
         # aliases
         if d['aliases']:
             ui.write(_("    aliases: %s\n\n") % " ".join(d['aliases']))
 
 
 def allextensionnames():
     return extensions.enabled().keys() + extensions.disabled().keys()
 
 if __name__ == "__main__":
     doc = 'hg.1.gendoc'
     if len(sys.argv) > 1:
         doc = sys.argv[1]
 
     ui = uimod.ui()
     if doc == 'hg.1.gendoc':
         showdoc(ui)
     else:
         showtopic(ui, sys.argv[1])

tests/test-install.t

@@ -1,138 +1,139
 hg debuginstall
   $ hg debuginstall
   checking encoding (ascii)...
   checking Python executable (*) (glob)
   checking Python version (2.*) (glob)
   checking Python lib (*lib*)... (glob)
   checking installed modules (*mercurial)... (glob)
   checking templates (*mercurial?templates)... (glob)
   checking default template (*mercurial?templates?map-cmdline.default) (glob)
   checking commit editor... (* -c "import sys; sys.exit(0)") (glob)
   checking username (test)
   no problems detected
 
 hg debuginstall JSON
   $ hg debuginstall -Tjson | sed 's|\\\\|\\|g'
   [
    {
     "defaulttemplate": "*mercurial?templates?map-cmdline.default", (glob)
     "defaulttemplateerror": null,
     "defaulttemplatenotfound": "default",
     "editor": "* -c \"import sys; sys.exit(0)\"", (glob)
     "editornotfound": false,
     "encoding": "ascii",
     "encodingerror": null,
     "extensionserror": null,
     "hgmodules": "*mercurial", (glob)
     "problems": 0,
     "pythonexe": "*", (glob)
     "pythonlib": "*", (glob)
     "pythonver": "*.*.*", (glob)
     "templatedirs": "*mercurial?templates", (glob)
     "username": "test",
     "usernameerror": null,
     "vinotfound": false
    }
   ]
 
 hg debuginstall with no username
   $ HGUSER= hg debuginstall
   checking encoding (ascii)...
   checking Python executable (*) (glob)
   checking Python version (2.*) (glob)
   checking Python lib (*lib*)... (glob)
   checking installed modules (*mercurial)... (glob)
   checking templates (*mercurial?templates)... (glob)
   checking default template (*mercurial?templates?map-cmdline.default) (glob)
   checking commit editor... (* -c "import sys; sys.exit(0)") (glob)
   checking username...
    no username supplied
    (specify a username in your configuration file)
   1 problems detected, please check your install!
   [1]
 
 path variables are expanded (~ is the same as $TESTTMP)
   $ mkdir tools
   $ touch tools/testeditor.exe
 #if execbit
   $ chmod 755 tools/testeditor.exe
 #endif
   $ hg debuginstall --config ui.editor=~/tools/testeditor.exe
   checking encoding (ascii)...
   checking Python executable (*) (glob)
   checking Python version (*) (glob)
   checking Python lib (*lib*)... (glob)
   checking installed modules (*mercurial)... (glob)
   checking templates (*mercurial?templates)... (glob)
   checking default template (*mercurial?templates?map-cmdline.default) (glob)
   checking commit editor... (* -c "import sys; sys.exit(0)") (glob)
   checking username (test)
   no problems detected
 
 #if test-repo
   $ cat >> wixxml.py << EOF
   > import os, subprocess, sys
   > import xml.etree.ElementTree as ET
   > 
   > # MSYS mangles the path if it expands $TESTDIR
   > testdir = os.environ['TESTDIR']
   > ns = {'wix' : 'http://schemas.microsoft.com/wix/2006/wi'}
   > 
   > def directory(node, relpath):
   >     '''generator of files in the xml node, rooted at relpath'''
   >     dirs = node.findall('./{%(wix)s}Directory' % ns)
   > 
   >     for d in dirs:
   >         for subfile in directory(d, relpath + d.attrib['Name'] + '/'):
   >             yield subfile
   > 
   >     files = node.findall('./{%(wix)s}Component/{%(wix)s}File' % ns)
   > 
   >     for f in files:
   >         yield relpath + f.attrib['Name']
   > 
   > def hgdirectory(relpath):
   >     '''generator of tracked files, rooted at relpath'''
   >     hgdir = "%s/../mercurial" % (testdir)
   >     args = ['hg', '--cwd', hgdir, 'files', relpath]
   >     proc = subprocess.Popen(args, stdout=subprocess.PIPE,
   >                             stderr=subprocess.PIPE)
   >     output = proc.communicate()[0]
   > 
   >     slash = '/'
   >     for line in output.splitlines():
   >         if os.name == 'nt':
   >             yield line.replace(os.sep, slash)
   >         else:
   >             yield line
   > 
   > tracked = [f for f in hgdirectory(sys.argv[1])]
   > 
   > xml = ET.parse("%s/../contrib/wix/%s.wxs" % (testdir, sys.argv[1]))
   > root = xml.getroot()
   > dir = root.find('.//{%(wix)s}DirectoryRef' % ns)
   > 
   > installed = [f for f in directory(dir, '')]
   > 
   > print('Not installed:')
   > for f in sorted(set(tracked) - set(installed)):
   >     print('  %s' % f)
   > 
   > print('Not tracked:')
   > for f in sorted(set(installed) - set(tracked)):
   >     print('  %s' % f)
   > EOF
 
   $ python wixxml.py help
   Not installed:
     help/common.txt
+    help/hg-ssh.8.txt
     help/hg.1.txt
     help/hgignore.5.txt
     help/hgrc.5.txt
   Not tracked:
 
   $ python wixxml.py templates
   Not installed:
   Not tracked:
 
 #endif