NAME
    Webhelp - help for the web interface

DESCRIPTION
    Help for users of the web interface, searching, objects and their
    fields, etc.

SEARCH
    form
        The search form has no pre-selected entries, click query and an
        indiscriminate list of all the bugs in the database will be
        returned.

        Filtering is achieved by selecting options from the popup menus, or
        entering data in the text fields, as described below.

        Once an item is returned for viewing, links to it's constituent
        parts may be followed.

        The following describe fields not described under "OBJECTS"

    admin
        List of active administrators who are registered against 1 or more
        bugs.

    boolean
        Boolean switch to decide whether or not to AND or to OR the query
        fields together, in the creation of the SQL search query.

    asc_desc
        Determine whether to return records found in ASCENDING or DESCENDING
        order.

    dates
        Restrict records created on or after the selected date.

        Note that you can also construct a query to retrieve the bugs since
        this Christmas by using something of the form:

                http://bugs.perl.org/perlbug/perlbug.cgi?req=date&date=20001225

        Usage of a valid 8 figure date is recommended, otherwise you're on
        your own :-)

    format
        Determine the display format of the records found. This for example,
        means you can still get an ascii list (for applying a script
        against, perhaps), even while using the web frontend which naturally
        has the default return format in HTML form.

    message_id
        The contents of the actual Message-Id: field belonging to each bug
        or reply.

    restrict
        Restrict the number of found records to the given number. Also
        divides the remainder up into similarly sized chunks for convenient
        browsing thereafter.

    messages
        Restrict returns to bugs which have this many messages/replies in
        the thread.

    show_sql
        Display the SQL executed. This may help to pinpoint problems where
        searches are not returning expected results.

    wildcards
        All text fields are searched using the SQL 'LIKE' operator. The LIKE
        operator allows the symbol % to match any sequence of characters,
        like '.*' in Perl regexes, and the symbol '_' to match any single
        character, like '.' in Perl regexes. Perlbug also maps '*' to '%',
        so '*' will also match any sequence of characters. All other
        characters in text boxes are taken literally.

        The Subject, Body and Source address fields perform substring
        searches. That is they are surrounded by % internally. For example,
        entering *filehandle* in the Subject box searches for any subject
        that contains the string *filehandle*.

        The Bug ID, Version, Fixed in, Message-ID, Note ID, Patch ID, and
        Test ID, fields are used exactly as entered. Entering '20001122' in
        the Bug ID field will not match anything, because 20001122 is not
        the ID of any bug. To find all the bugs that were submitted on date
        20001122, use '20001122.%'.

        Note also that for convenience(?), an asterisk("*") will be simply
        mapped to the sql wildcard "%"'.

        It may be instructive to try a few searches with the Show SQL option
        enabled. This will display the SQL query that the engine is using to
        search the database.

        See also "object_search"

    retrieval
        Bugs are initially returned in either list or block format, with an
        optional trimming mechanism which defaults to 25. At the base of the
        page is a list of all the other bugs found during the query,
        sectioned into similarly managable portions. The list format is
        designed for quickly moving around a list of bugs, while the block
        format is aimed at finding all information relating to said bug,
        without having to hop around.

  Searching for objects
    object_search
        Where searching for each object, (not using the prime bug search
        mechanism), individually, each field is treated as searchable using
        the wildcard mechanism described above.

        The following fields are treated specially:

    created
        Date field - use a format of YYYY-MM--DD eg; 1987-05-02

    modified
        As per "created" above

    optional
        The Optional field is used by administrators to enter a command line
        string for defining relationships, similar to a typical bugdb
        subject or To|Cc line.

        For example to assign group, status, admin info etc. to a bug:

        "aix linux win98 macos closed richardf docs"

        Or a bugid, or two, to a patch:

        "19870502.007 19870502.091"

        See mailhelp for more info

        "DESCRIPTION"

SUBMIT
        The submit buttons available are as follows:

    Query
        submit the query to the database interface

    Reset
        reset the form to the default values

  administrative
        For admins only:

    Update
        update the selected record/s shown

    Nocc
        same as update, but don't send any email notifications of the
        changes

    Select
        select all shown record/s

    Unselect
        deselect all shown record/s

    Admin
        switch from the noadmin view to the admin view (data updates are
        possible)

    Noadmin
        switch from the admin view to the noadmin view (less clutter)

    Delete
        delete the selected shown record/s

OBJECTS
    Certain fields are common to all objects:

    created
        The date this record was created in the database.

    modified
        The date this record was in some way modified.

    history
        The list of all modifications to each item, and who submitted them.

    transfer
        Certain objects may be transferred from one type to another, for
        example where a plain "message" should be reclassified as, for
        example, a "patch" or a "test".

        Additional data may always be entered in the "optional" field

BUG
    The main potato:

    bugid
        The internally generated bugid.

    subject
        The subject line of the original report.

    source_addr
        Usually the From: address of the original report.

    body
        The body of the original message which generated the bug report.

        During a web search, the bodies of all messages in the database will
        be inspected, unless the boolean "and_or" switch AND is selected
        whereby the search criteria is narrowed down.

    status
        The status of the bug, with the following options:

            abandoned   -       no longer worked on

            busy        -       currently being looked at by an administrator

            closed      -       considered fixed

            duplicate   -       a report erroneously filed a second time

            incapable   -       considered not doable

            ok          -       a 'build reported OK:' report, (not the same as closed)

            notok         -     opposite of B<ok>

            onhold      -       undecided as to whether this is a bug or not

            open        -       undealt with, needing attention

    group
        The group (or category) of the bug has the following options:

            bounce      -       report had invalid format, common with spam mail

            core        -       central functionality affected

            docs        -       not a code bug, a docs bug (or typo)

            install     -       bug in the installation procedure

            library     -       not a central routine, rather a library or module bug

            notabug     -       at all, could be misread instructions or even spam

            patch       -       this fixed another bug

            unknown     -       first port of call, bug usually assigned to another valid group 

            utilities   -       a utility function misbehaved

    severity
        The severity of the bug has the following options, in descending
        order or severity:

            fatal       -       top priority!

            high        -       non-fatal, but has to be fixed quickly

            medium      -       should be fixed soon

            low         -       would be good to fix when time permits

            wishlist    -       would be nice to have someone look at this sometime

            none        -       a bit like 'wishlist' but more so

    osname
        The name of the operating system this report was generated on:

        Many differing values possible.

                aix, dec, hpux, irix, linux, macos, next, os2, solaris, vms, winnt, etc.

                ...     
        
    project
        The Project, which currently uses the

                perl4           - once 

                perl5           - and [now]

                perl6           - future

                ...

    VERSIONING
        There are several field relating to versions, patches, changes which
        may at first be somewhat inter-related.

    version
        The version against which this report was first noticed/generated.

        Typically has one of the following forms:

                5

                5.0053

                5.00.5.3

                5.6

                5.6.0

                5.7.1

                ...

    fixed
        The version in which this bug was fixed, same format as "version"
        above.

    change
        The changeID of the target source for the fix. this is an external
        reference about which we know very little.

        Typically has one of the following forms:

                5

                5810

                0053

                ...

    history
        History of administrative operations against this bug, changes of
        status/group, etc..

    cc  List of email addresses for this bug. Will contain the source
        address, any adminitrator who has modified the bug record, and any
        people who have been on the Cc: list of any of the messages assigned
        to this bug.

    messagids
        The internal-ids of messages belonging to this bug (replies).

        Not to be confused with the externally supplied "message_id"'s of
        each email.

    parent
        The "bugid" of any other bug to which this bug may belong.

    child
        The "bugid" of any other bug which belongs to this bug.

    DESCRIPTION

NOTE
    An administrator can assign a note to a bug when he/she modifies it.

    note
        The body of the note.

    noteid
        The internally generated noteid.

    DESCRIPTION

PATCH
    A bug may be fixed by a patch, this can be assigned along with a
    "changeid".

    Bear in mind the difference between the internally generated /patchid
    and the externally offered /changeid.

    patch
        The body of the patch.

    patchid
        The internally generated patchid.

    DESCRIPTION

TEST
    A test may be assigned to a bug, if the test succeeds the bug may be
    regarded as fixed.

    test
        The body of the test.

    testid
        The internally generated testid.

    DESCRIPTION

AUTHOR
    Richard Foley <richard@rfi.net> 2001

    Amendments by Mark-Jason Dominus <mjd@plover.com>

