[MERGE] bzr help locationspec

[Martin Pool]

On 16 Jan 2007, John Arbash Meinel <john at arbash-meinel.com> wrote:
> > Hi Marius,
> > 
> > I agree, adding this now is better than nothing, and we can do more
> > later.  So +1
> 
> This is a little bit of what Registry was meant to help with. So that we
> can change the Transport registry, and at registration time, we could
> possibly include a 'hidden' or 'internal-only' flag.

+1 

> One other thing is that http+urllib and http+pycurl are probably useful,
> though maybe only as debugging... I'm not really sure.
> 
> Internally all these are transports, so we *could* do "bzr help
> transports". But that could be too much of an implementation detail
> versus 'bzr help urls'. Maybe 'bzr help supported-protocols' or 'bzr
> help protocols'?  Because it isn't really the whole url that we are
> talking about, just the protocol portion.

Yes I'd tend to steer away from 'transports' as the main name for the
topic, but add it as a synonym since people may encounter the word.

> I agree, when possible we should create documentation from the internal
> help rather than having 2 sets of internal and external help.
> 
> Though someone (fullermd?) had a good point about online versus offline
> documenation. Which is that online (bzr help) is really just meant as a
> reminder, versus offline (doc/*) is meant to be a verbose discussion of
> the tradeoffs between different styles, etc.
> 
> So where the documentation would be the same, I would like to see it
> come from reprocessed internal help. Where we want to expand, it
> probably would be external.

I think we do want the two styles of documentation - quick reference and
then a longer form.  But until we get to really extended documents, I
think they can be stored in the same mechanism, so they can be easily
found etc.

(I think we could use packageresources to load them from text files
rather than being stored in quoted strings.)

> Well, technically you can iterate over
> bzrlib.transport._protocol_handlers. But that isn't a very good api. And
> I'd really rather have a:
> bzrlib.transport.transport_registry.keys() call to give you back all of
> the names of registered protocols.

Goffredo's patch looks at _protocol_handlers, but otherwise seems to go
in the right direction.  I'll pull that in.

Credit is certainly still due to Marius for reminding us to fix it...

> So I'm +1 on the documentation improvements, but I would like us to
> finalize what help topic it falls under, just so it doesn't have to move
> around much afterwards.
> 
> Current suggestions are:
> 
>   locationspec
>   url
>   urls
>   protocol
>   protocols
>   transport
>   transports
> 
> I would probably vote for 'protocols' as my favorite. Though we also
> would need to decide on plural form versus singular.

OK with me - can help topics have aliases like commands? (I'll look)

-- 
Martin