{"thread":{"id":"52757","subject":"Support 'help' for custom/alias commands","startedAt":"2020-02-07T11:02:27Z","lastAt":"2020-02-09T16:39:20Z","messageCount":6,"participants":["paul@pauldsmith.org.uk","Konstantin Khomoutov","brian m. carlson"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"391317","messageId":"005001d5dda3$5bc12510$13436f30$@pauldsmith.org.uk","threadId":"52757","inReplyTo":"VI1P192MB025548BB0508125DF9B5852DC81C0@VI1P192MB0255.EURP192.PROD.OUTLOOK.COM","subject":"Support 'help' for custom/alias commands","fromName":"","fromEmail":"paul@pauldsmith.org.uk","sentAt":null,"receivedAt":"2020-02-07T11:02:27Z","isPatch":false,"sender":{"key":"paul@pauldsmith.org.uk","avatar":"https://gravatar.com/avatar/7d329d141a1df182832f044fb3b4a338e90cb65a6b8c3c25de14314b1a297c3b?d=mp&s=160"},"body":"Adding a custom comment (let’s call is ‘foolish’) is easy but then you\nsomeone types ‘git help foolish’, they get some strange message about help\nnot being found.\n\nThere are two problems with this:\n\n1. It’s hard for users to create good documentation in the same format as\nthe core git product 2. The git ‘help’ processing currently looks in one,\nand one place only and that location is often ‘locked down’ meaning that\nmere users cannot add their custom help to this directory.\n\nI propose that #1 be solved by creating a command/tool and documentation\nthat explains how to mimic the input to the standard Git help files and have\nthem processed to create the HTML/HTML5/MAN help normally produced.  Ideally\nit would do exactly the same processing as the core tools (perhaps even\nhaving their docs built using this tool now) and use exactly the same\ntemplate files that core git uses.\n\nI propose that #2 be solved by allowing a new set of ‘git config’ fields.\nThe layout should be sensible and should users to be able to set a git\nvariable which then means that the core git help finds their help text.\nPossible we want to force\n\n/docs/man, or html, or html5\n\nAnd the git config variable be something like\n“help.custom.foolish=/docs”\n\nPaul DS.\n\nP.S. I have a perfectly respectable e-mail address at\npaul_d_smith@hotmail.com which I have used for years - why won't you accept\ne-mails from it?\n\n\n\n"},{"id":"391319","messageId":"20200207112948.et2t4r4mhh2wkqbr@carbon","threadId":"52757","inReplyTo":"005001d5dda3$5bc12510$13436f30$@pauldsmith.org.uk","subject":"Re: Support 'help' for custom/alias commands","fromName":"Konstantin Khomoutov","fromEmail":"kostix@bswap.ru","sentAt":"2020-02-07T11:29:48Z","receivedAt":"2020-02-07T11:30:02Z","isPatch":false,"sender":{"key":"kostix@bswap.ru","avatar":null},"body":"On Fri, Feb 07, 2020 at 10:42:56AM -0000, paul@pauldsmith.org.uk wrote:\n\n[...]\n> P.S. I have a perfectly respectable e-mail address at\n> paul_d_smith@hotmail.com which I have used for years - why won't you accept\n> e-mails from it?\n\nThe filters at vger.kernel.org do not allow mails which contain\ntext/html parts (mails which contain _only_ them are surely dropped; not\nsure about mails with multipart/alternative, which do contain a\ntext/plain counterpart). Was this the case?\n\n"},{"id":"391358","messageId":"20200207234618.GH6573@camp.crustytoothpaste.net","threadId":"52757","inReplyTo":"005001d5dda3$5bc12510$13436f30$@pauldsmith.org.uk","subject":"Re: Support 'help' for custom/alias commands","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-02-07T23:46:18Z","receivedAt":"2020-02-07T23:46:26Z","isPatch":false,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2020-02-07 at 10:42:56, paul@pauldsmith.org.uk wrote:\n> Adding a custom comment (let’s call is ‘foolish’) is easy but then you\n> someone types ‘git help foolish’, they get some strange message about help\n> not being found.\n> \n> There are two problems with this:\n> \n> 1. It’s hard for users to create good documentation in the same format as\n> the core git product 2. The git ‘help’ processing currently looks in one,\n> and one place only and that location is often ‘locked down’ meaning that\n> mere users cannot add their custom help to this directory.\n\nIt is possible to extend the set of locations that one can use for man\nby setting MANPATH. If you do so, something like \"git foolish --help\"\ndoes indeed work.\n\n> I propose that #1 be solved by creating a command/tool and documentation\n> that explains how to mimic the input to the standard Git help files and have\n> them processed to create the HTML/HTML5/MAN help normally produced.  Ideally\n> it would do exactly the same processing as the core tools (perhaps even\n> having their docs built using this tool now) and use exactly the same\n> template files that core git uses.\n\nThere is such a tool, and it's called Asciidoctor. However, it's\nwritten in Ruby, and not all users will want to install Ruby as part of\ntheir Git installation. It does work nicely, though, and I use it for\nmy own custom Git subcommands.\n\nAlso, if a user prefers to use a different tool for creating manual\npages or HTML documentation, they can certainly do so.\n\n> I propose that #2 be solved by allowing a new set of ‘git config’ fields.\n> The layout should be sensible and should users to be able to set a git\n> variable which then means that the core git help finds their help text.\n> Possible we want to force\n> \n> /docs/man, or html, or html5\n> \n> And the git config variable be something like\n> “help.custom.foolish=/docs”\n\nI think specifying a single location may be a problem because different\ntypes of documentation live in different locations. On Debian, man\npages live in /usr/share/man, but HTML documentation lives in\n/usr/share/doc.\n\nWe could theoretically add support for this if we did help.foolish.man\nand help.foolish.html, though.\n\nI don't feel strongly enough about this to implement it, but if you're\ninterested, I could review a patch.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"391391","messageId":"00df01d5df4a$e422af70$ac680e50$@pauldsmith.org.uk","threadId":"52757","inReplyTo":"20200207234618.GH6573@camp.crustytoothpaste.net","subject":"RE: Support 'help' for custom/alias commands","fromName":"","fromEmail":"paul@pauldsmith.org.uk","sentAt":null,"receivedAt":"2020-02-09T13:14:47Z","isPatch":false,"sender":{"key":"paul@pauldsmith.org.uk","avatar":"https://gravatar.com/avatar/7d329d141a1df182832f044fb3b4a338e90cb65a6b8c3c25de14314b1a297c3b?d=mp&s=160"},"body":"Brian,\n\nThanks for considering this. I've not tried MANPATH but will take a look - my employers use both Linux and Windows so this would only address half the issue but I also understand your comments on \"one config to rule them all\" and the HTML/MAN issue.\n\nI've used ASCIIDOCTOR already to create config but I feel it would be nice if that could be rolled up into some sort of bundle but it users don't want Ruby then yes, it's not going to work for them. My personal take is that anyone wanting docs for their custom applications should create them like core Git does - and with Docker and similar it's easy to isolate an environment so perhaps a Docker image might be the way to go.\n\nClearly room for a little more thought on my part.\n\nRegards,\nPaul DS\n\n-----Original Message-----\nFrom: brian m. carlson \nSent: 07 February 2020 23:46\nTo: paul@pauldsmith.org.uk\nCc: git@vger.kernel.org\nSubject: Re: Support 'help' for custom/alias commands\n\nOn 2020-02-07 at 10:42:56, paul@pauldsmith.org.uk wrote:\n> Adding a custom comment (let’s call is ‘foolish’) is easy but then you \n> someone types ‘git help foolish’, they get some strange message about \n> help not being found.\n> \n> There are two problems with this:\n> \n> 1. It’s hard for users to create good documentation in the same format \n> as the core git product 2. The git ‘help’ processing currently looks \n> in one, and one place only and that location is often ‘locked down’ \n> meaning that mere users cannot add their custom help to this directory.\n\nIt is possible to extend the set of locations that one can use for man by setting MANPATH. If you do so, something like \"git foolish --help\"\ndoes indeed work.\n\n> I propose that #1 be solved by creating a command/tool and \n> documentation that explains how to mimic the input to the standard Git \n> help files and have them processed to create the HTML/HTML5/MAN help \n> normally produced. Ideally it would do exactly the same processing as \n> the core tools (perhaps even having their docs built using this tool \n> now) and use exactly the same template files that core git uses.\n\nThere is such a tool, and it's called Asciidoctor. However, it's written in Ruby, and not all users will want to install Ruby as part of their Git installation. It does work nicely, though, and I use it for my own custom Git subcommands.\n\nAlso, if a user prefers to use a different tool for creating manual pages or HTML documentation, they can certainly do so.\n\n> I propose that #2 be solved by allowing a new set of ‘git config’ fields.\n> The layout should be sensible and should users to be able to set a git \n> variable which then means that the core git help finds their help text.\n> Possible we want to force\n> \n> /docs/man, or html, or html5\n> \n> And the git config variable be something like \n> “help.custom.foolish=/docs”\n\nI think specifying a single location may be a problem because different types of documentation live in different locations. On Debian, man pages live in /usr/share/man, but HTML documentation lives in /usr/share/doc.\n\nWe could theoretically add support for this if we did help.foolish.man and help.foolish.html, though.\n\nI don't feel strongly enough about this to implement it, but if you're interested, I could review a patch.\n--\nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n\n"},{"id":"391392","messageId":"00e001d5df4b$1a042c40$4e0c84c0$@pauldsmith.org.uk","threadId":"52757","inReplyTo":"20200207112948.et2t4r4mhh2wkqbr@carbon","subject":"RE: Support 'help' for custom/alias commands","fromName":"","fromEmail":"paul@pauldsmith.org.uk","sentAt":null,"receivedAt":"2020-02-09T13:16:17Z","isPatch":false,"sender":{"key":"paul@pauldsmith.org.uk","avatar":"https://gravatar.com/avatar/7d329d141a1df182832f044fb3b4a338e90cb65a6b8c3c25de14314b1a297c3b?d=mp&s=160"},"body":"Possibly. I use Outlook as my mail client and did select \"Plain Text\" for\nboth e-mail attempts. The error message implied it was the sending e-mail\naddress (paul_d_smith@hotmail.com) that it didn't like, not the e-mail\nitself.\n\nRegards,\nPaul DS.\n\n-----Original Message-----\nFrom: Konstantin Khomoutov \nSent: 07 February 2020 11:30\nTo: paul@pauldsmith.org.uk\nCc: git@vger.kernel.org\nSubject: Re: Support 'help' for custom/alias commands\n\nOn Fri, Feb 07, 2020 at 10:42:56AM -0000, paul@pauldsmith.org.uk wrote:\n\n[...]\n> P.S. I have a perfectly respectable e-mail address at \n> paul_d_smith@hotmail.com which I have used for years - why won't you \n> accept e-mails from it?\n\nThe filters at vger.kernel.org do not allow mails which contain text/html\nparts (mails which contain _only_ them are surely dropped; not sure about\nmails with multipart/alternative, which do contain a text/plain\ncounterpart). Was this the case?\n\n"},{"id":"391406","messageId":"20200209163857.GA7054@camp.crustytoothpaste.net","threadId":"52757","inReplyTo":"00df01d5df4a$e422af70$ac680e50$@pauldsmith.org.uk","subject":"Re: Support 'help' for custom/alias commands","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-02-09T16:38:57Z","receivedAt":"2020-02-09T16:39:20Z","isPatch":false,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2020-02-09 at 13:14:42, paul@pauldsmith.org.uk wrote:\n> Brian,\n> \n> Thanks for considering this. I've not tried MANPATH but will take a look - my employers use both Linux and Windows so this would only address half the issue but I also understand your comments on \"one config to rule them all\" and the HTML/MAN issue.\n> \n> I've used ASCIIDOCTOR already to create config but I feel it would be nice if that could be rolled up into some sort of bundle but it users don't want Ruby then yes, it's not going to work for them. My personal take is that anyone wanting docs for their custom applications should create them like core Git does - and with Docker and similar it's easy to isolate an environment so perhaps a Docker image might be the way to go.\n\nI don't see a problem with us shipping the stylesheets and tooling we\nuse for our conversions as something people can use, and then if they\nwant to install AsciiDoc or Asciidoctor, they can use the same scripts.\nThat wouldn't be that hard to do.\n\nPersonally, though, I find that I don't benefit from them much when I\nwrite documentation, and so I don't use them. Other people may feel\ndifferently, though.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"}]}