[PATCH] help: 'hg help' supports list of subtopics (issue2804)

[Martin Geisler]

(Sending again, I cannot find it in the archive)

Yun Lee <yun.lee.bj at gmail.com> writes:

> # HG changeset patch
> # User Yun Lee <yun.lee.bj at gmail.com>
> # Date 1306162477 -28800
> # Branch stable
> # Node ID a8ddc45c104873c84f3618895e1936d8307f6db2
> # Parent  3c65cdcf3ba6cdaa75e7b9e6eb8ef0ff0d3db197
> help: 'hg help' supports list of subtopics (issue2804)

Hi Yun,

It is cool that you have working code, but we should talk a little about
the plan here. I had a talk on IRC with Matt about this, and here are
the log with my comments in between:

  <mpm> I think step 0 is: move the whole damn doc into the config topic
        and let pager deal with it.
  <mpm> Can we agree that that's forward progress?
  <mg> mpm: agree on step 0, definitely

So move the text from doc/hgrc.5.txt to mercurial/help/config.txt, just
putting it at the bottom should be fine.

  <mpm> Now, once we've done that, I think teaching help how to find
        subsections of topics based on mark-up is a lot better than
        being table-based.
  <mg> mpm: yeah, I like that idea!

The advantage is that we don't have a hard-coded table in the source
code with the topics and their sub-topics.

  <mpm> This implies we can access any topic in a tree-like fashion:
        topic->subheading[->subsubheading?]
  <mpm> So if I want to find help on, say, aliases, I'll type 'hg help
        -k alias'..
  <mpm> And it'll say something like..
  <mpm> config alias: "Defines command aliases. Aliases allow you to
        define your own commands..."
  <mpm> (synopsis from the start of that help)
  <mg> okay
  <mpm> Then you type 'hg help config alias'...
  <mg> so no direct 'hg help ui.username'?
  <mpm> We might special-case hgrc settings, but I think in the general
        case, it should be path-like..
  <mpm> ie 'config aliases' or 'config:aliases' or 'config/aliases' or
        something.
  <mg> yeah, that sounds good
  <mg> mpm: I just don't want the 'hg help config.ui.username' since that looks
       quite weird to me

The config help topic will be large, but will have headings for the
different sections and settings. So 'hg help -k' should be able to
search through the topic and recognize the headings.

The minirst parser already knows how to recognize a heading, so that
should help here. I suggest that the first paragraph after the heading
is used as the synopsis.

  <mpm> Ok, so: step 0 -> move config help.

This is the easy step.

  <mpm> step 1 -> implement 'hg help <section> <subsection>'

This implies making 'hg help' do the parsing we talk about above.

  <mpm> step 2 -> add a special case for ui.username-style config settings.

This is a nice-to-have for the future.

  <mpm> mg: I don't care how we refer to <section> <subsection>, but I think
        we're agree, '.' separators is confusing here.
  <mg> mpm: yeah

I would like to be able to do 'hg help ui.username' at some point. I
think that would then be the same as 'hg help config ui username', which
finds the 'username' sub-section in the 'ui' section in the 'config'
help topic.

I'm normally online on IRC from 9-18 in the UTC+1 timezone:

  http://timeanddate.com/worldclock/city.html?n=268

I've added a table here

  http://mercurial.selenic.com/wiki/IRC#Timezones

-- 
Martin Geisler

aragost Trifork
Professional Mercurial support
http://mercurial.aragost.com/kick-start/