D2678: help: supporting both help and doc for aliases

mharbison72 (Matt Harbison) phabricator at mercurial-scm.org
Tue Mar 6 21:21:19 EST 2018


mharbison72 added a comment.


  In https://phab.mercurial-scm.org/D2678#43533, @spectral wrote:
  
  > (I'm stepping in and responding while rdamazio is out for a few days)
  >
  > In https://phab.mercurial-scm.org/D2678#43299, @mharbison72 wrote:
  >
  > > I really like this feature too.  Any plans to extend it to {fileset,revset,template}alias?
  >
  >
  > We don't have any concrete plans to do so, but would not be opposed.
  >
  > > I don't think this should prevent it from being accepted, but is there a way to get the help text rendered as-is, without reflowing?  For example, to simulate the usual 1 line summary + extended detail, I tried:
  > > 
  > >   [alias]
  > >   phabimport:doc = Import a stack of revisions from phabricator.
  > >     .
  > >     This is extended help.
  > > 
  > > 
  > > That got me:
  > > 
  > >   $ ../hg help phabimport
  > >   hg phabimport
  > >   
  > >   shell alias for: "%HG%" phabread $1 | "%HG%" import --bypass -
  > >   
  > >   Import a stack of revisions from phabricator. . This is extended help.
  > >   
  > >   defined by: c:\Users\Matt\projects\hg\.hg\hgrc:28
  > >   
  > >   (some details hidden, use --verbose to show complete help)
  > > 
  > > 
  > > (The middle '.' line is necessary, because the config parser throws away empty lines, complains about unexpected leading whitespace in the next line, and then exits without the usual 'abort: ' prefix.  That bad format even kills `hg version`, but the output does indicate exactly where the problem is.)
  >
  > I don't think that it'll be easy to make it avoid reflowing, I believe that's a pretty low-level aspect of the help command.
  
  
  Yeah, avoiding reflow in general is too broad.  It is useful, until trying to make paragraphs or the table of options at the bottom of a help command.
  
  > It would be better to fix the command parser to allow interstitial blank lines, but I don't have an estimate on how hard that would be.
  
  That's probably not enough for things beyond paragraph breaks, like the options table.  FWIW, `hg help config.syntax` does say such lines are skipped.  IDK what changing that would break if extra blank lines happen to be after a random option.
  
  > Looks like our internal use of the feature from this patch is avoiding multi-line messages, I don't know if this is because they don't work, or because rdamazio didn't try it.  I agree it should hopefully not block the review in the meantime, especially if the desired+expected end-goal is that the config parser lets us have the blank lines (because then we won't need to change the text in a BC way; if we can't get the config parser to work, we may need to have this parse the text looking for things like \n, which could possibly be BC [though so mild I suspect it'll not be a problem])
  
  Maybe breaking after an explicit '\n' (string) which doesn't have an escaping '\' is the way to go.  I think templates support similar in that the lines for the item are all joined, and then the visible '\n' become hard breaks.  Assuming the code that injects it into the help system is what makes the substitution, I'm not sure where the BC comes in (unless you mean FB might have '\n' which should be rendered literally).  I don't know much about the help rendering though, so I have no idea how easy this is.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D2678

To: rdamazio, #hg-reviewers
Cc: mharbison72, spectral, pulkit, mercurial-devel


More information about the Mercurial-devel mailing list