~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/commands.py

  • Committer: Ian Clatworthy
  • Date: 2007-08-06 08:25:46 UTC
  • mto: (2674.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 2675.
  • Revision ID: ian.clatworthy@internode.on.net-20070806082546-oup6ujeleehqoqfj
Bazaar User Reference generated from online help

Show diffs side-by-side

added added

removed removed

Lines of Context:
274
274
        s = s[:-1]
275
275
        return s
276
276
 
277
 
    def get_help_text(self, additional_see_also=None):
 
277
    def get_help_text(self, additional_see_also=None, plain=True):
278
278
        """Return a text string with help for this command.
279
279
        
280
280
        :param additional_see_also: Additional help topics to be
281
281
            cross-referenced.
 
282
        :param plain: if False, raw help (reStructuredText) is
 
283
            returned instead of plain text.
282
284
        """
283
285
        doc = self.help()
284
286
        if doc is None:
285
287
            raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
286
288
 
 
289
        # Extract the summary (purpose) and sections out from the text
 
290
        purpose,sections = self._get_help_parts(doc)
 
291
 
 
292
        # If a custom usage section was provided, use it
 
293
        if sections.has_key('Usage'):
 
294
            usage = sections.pop('Usage')
 
295
        else:
 
296
            usage = self._usage()
 
297
 
 
298
        # The header is the purpose and usage
287
299
        result = ""
288
 
        result += 'usage: %s\n' % self._usage()
289
 
 
 
300
        result += ':Purpose: %s\n' % purpose
 
301
        if usage.find('\n') >= 0:
 
302
            result += ':Usage:\n%s\n' % usage
 
303
        else:
 
304
            result += ':Usage:   %s\n' % usage
 
305
        result += '\n'
 
306
 
 
307
        # Add the options
 
308
        options = option.get_optparser(self.options()).format_option_help()
 
309
        if options.startswith('Options:'):
 
310
            result += ':' + options
 
311
        else:
 
312
            result += options
 
313
        result += '\n'
 
314
 
 
315
        # Add the description, indenting it 2 spaces
 
316
        # to match the indentation of the options
 
317
        if sections.has_key(None):
 
318
            text = sections.pop(None)
 
319
            text = '\n  '.join(text.splitlines())
 
320
            result += ':%s:\n  %s\n\n' % ('Description',text)
 
321
 
 
322
        # Add the custom sections (e.g. Examples). Note that there's no need
 
323
        # to indent these as they must be indented already in the source.
 
324
        if sections:
 
325
            labels = sorted(sections.keys())
 
326
            for label in labels:
 
327
                result += ':%s:\n%s\n\n' % (label,sections[label])
 
328
 
 
329
        # Add the aliases, source (plug-in) and see also links, if any
290
330
        if self.aliases:
291
 
            result += 'aliases: '
 
331
            result += ':Aliases:  '
292
332
            result += ', '.join(self.aliases) + '\n'
293
 
 
294
 
        result += '\n'
295
 
 
296
333
        plugin_name = self.plugin_name()
297
334
        if plugin_name is not None:
298
 
            result += '(From plugin "%s")' % plugin_name
299
 
            result += '\n\n'
300
 
 
301
 
        result += doc
302
 
        if result[-1] != '\n':
303
 
            result += '\n'
304
 
        result += '\n'
305
 
        result += option.get_optparser(self.options()).format_option_help()
 
335
            result += ':From:     plugin "%s"\n' % plugin_name
306
336
        see_also = self.get_see_also(additional_see_also)
307
337
        if see_also:
308
 
            result += '\nSee also: '
309
 
            result += ', '.join(see_also)
310
 
            result += '\n'
 
338
            result += ':See also: '
 
339
            result += ', '.join(see_also) + '\n'
 
340
 
 
341
        # If this will be rendered as plan text, convert it
 
342
        if plain:
 
343
            import bzrlib.help_topics
 
344
            result = bzrlib.help_topics.help_as_plain_text(result)
311
345
        return result
312
346
 
 
347
    @staticmethod
 
348
    def _get_help_parts(text):
 
349
        """Split help text into a summary and named sections.
 
350
 
 
351
        :return: (summary,sections) where summary is the top line and
 
352
            sections is a dictionary of the rest indexed by section name.
 
353
            A section starts with a heading line of the form ":xxx:".
 
354
            Indented text on following lines is the section value.
 
355
            All text found outside a named section is assigned to the
 
356
            default section which is given the key of None.
 
357
        """
 
358
        def save_section(sections, label, section):
 
359
            if len(section) > 0:
 
360
                if sections.has_key(label):
 
361
                    sections[label] += '\n' + section
 
362
                else:
 
363
                    sections[label] = section
 
364
            
 
365
        lines = text.rstrip().splitlines()
 
366
        summary = lines.pop(0)
 
367
        sections = {}
 
368
        label,section = None,''
 
369
        for line in lines:
 
370
            if line.startswith(':') and line.endswith(':') and len(line) > 2:
 
371
                save_section(sections, label, section)
 
372
                label,section = line[1:-1],''
 
373
            elif label != None and len(line) > 1 and not line[0].isspace():
 
374
                save_section(sections, label, section)
 
375
                label,section = None,line
 
376
            else:
 
377
                if len(section) > 0:
 
378
                    section += '\n' + line
 
379
                else:
 
380
                    section = line
 
381
        save_section(sections, label, section)
 
382
        return summary, sections
 
383
 
313
384
    def get_help_topic(self):
314
385
        """Return the commands help topic - its name."""
315
386
        return self.name()