'find a man page by its name, everything following the last dot (.) in name,
is taken as the section of the man page
we return the man page found with the highest score, and a list of
suggestions that also matched the given name (only the first item
is prepopulated with the option data)'

def findmanpage(self, name):

    if name.endswith('.gz'):
        logger.info('name    ends    with    .gz,    looking    up    an    exact    match    by    source')
        d = self.manpage.find_one({'source': name})
        if (not d):
            raise errors.ProgramDoesNotExist(name)
        m = manpage.from_store(d)
        logger.info('returning    %s', m)
        return [m]
    section = None
    origname = name
    if (name != '.'):
        splitted = name.rsplit('.', 1)
        name = splitted[0]
        if (len(splitted) > 1):
            section = splitted[1]
    logger.info('looking    up    manpage    in    mapping    with    src    %r', name)
    cursor = self.mapping.find({'src': name})
    count = cursor.count()
    if (not count):
        raise errors.ProgramDoesNotExist(name)
    dsts = dict(((d['dst'], d['score']) for d in cursor))
    cursor = self.manpage.find({'_id': {'$in': list(dsts.keys())}}, {'name': 1, 'source': 1})
    if (cursor.count() != len(dsts)):
        logger.error('one    of    %r    mappings    is    missing    in    manpage    collection    (%d    mappings,    %d    found)', dsts, len(dsts), cursor.count())
    results = [(d.pop('_id'), manpage.from_store_name_only(**d)) for d in cursor]
    results.sort(key=(lambda x: dsts.get(x[0], 0)), reverse=True)
    logger.info('got    %s', results)
    if (section is not None):
        if (len(results) > 1):
            results.sort(key=(lambda (oid, m): (m.section == section)), reverse=True)
            logger.info('sorting    %r    so    %s    is    first', results, section)
        if (not (results[0][1].section == section)):
            raise errors.ProgramDoesNotExist(origname)
        results.extend(self._discovermanpagesuggestions(results[0][0], results))
    oid = results[0][0]
    results = [x[1] for x in results]
    results[0] = manpage.from_store(self.manpage.find_one({'_id': oid}))
    return results
