|
|
| Line 61: |
Line 61: |
| * [https://svn.jj5.net/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php?pathrev=1489#l4875 bugslist.php]: [http://php.net/manual/en/function.preg-match.php PHP preg_match()] | | * [https://svn.jj5.net/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php?pathrev=1489#l4875 bugslist.php]: [http://php.net/manual/en/function.preg-match.php PHP preg_match()] |
| * [https://svn.jj5.net/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php?pathrev=1489#l5086 bugslist.php]: [http://php.net/manual/en/errorfunc.constants.php PHP error constants] | | * [https://svn.jj5.net/jjrepo/jj5-bin/trunk/bin/bugslist.d/bugslist.php?pathrev=1489#l5086 bugslist.php]: [http://php.net/manual/en/errorfunc.constants.php PHP error constants] |
|
| |
| == Help ==
| |
|
| |
| '''Usage:''' php path/to/bugslist.php [OPTION]...
| |
| This is a source code processing and reporting tool to help with software
| |
| development project management. It processes files in the specified
| |
| directory and matches special comment syntax to get notes and work items
| |
| which it then reports on. Output reports are in MediaWiki wiki text syntax
| |
| designed to be included in your project wiki.
| |
|
| |
| === Comment label syntax ===
| |
|
| |
| The heart of bugslist.php is the comment label syntax you use in your
| |
| source code. It's basically:
| |
| DATE USER DASH TYPE[PRIORITY][:!] TEXT
| |
| For example: 2017-03-12 jj5 - HACK[HIGH]: expedient, you say?
| |
| The date is in ISO format, the user must be a valid UNIX user, and the dash
| |
| is just to try and limit false positives. The TYPE indicates what sort of
| |
| item this is; it can be one of the types listed below. Your type can be
| |
| suffixed with an optional priority within square brackets. After the
| |
| optional priority your type must be suffixed with punctuation, either ':' or
| |
| '!'. The TEXT follows until the end of the line and on to subsequent lines too.
| |
|
| |
| ==== Item types ====
| |
|
| |
| The following item types are supported in comment labels:
| |
|
| |
| Type................: Description..............................: Priority..:
| |
| Red-flags..........:
| |
| WARNING...........: something to be careful of...............: HIGH
| |
| TEMP..............: a note for code that should be removed...: HIGH
| |
| Stuff to do........:
| |
| BUG...............: something that needs to be fixed.........: HIGH
| |
| TEST..............: something that needs to be tested........: HIGH
| |
| TODO..............: something that needs to be done..........: MEDIUM
| |
| FIXME............: a HIGH priority alias for TODO...........: HIGH
| |
| NICE.............: a LOW priority alias for TODO............: LOW
| |
| HACK..............: something that needs to be improved......: LOW
| |
| CONSIDER..........: something to consider or think about.....: LOW
| |
| THINK............: an alias for CONSIDER....................: LOW
| |
| Stuff that's done..:
| |
| FIXED.............: a BUG that has been fixed................: HIGH
| |
| DONE..............: something that has been done.............: MEDIUM
| |
| COMMIT............: a VCS commit log.........................: LOW
| |
| Notes..............:
| |
| REFERENCE.........: a reference, e.g. a URL..................: LOW
| |
| REF..............: an alias for REFERENCE...................: LOW
| |
| SEE..............: an alias for REFERENCE...................: LOW
| |
| NOTE..............: notes, or items without a label..........: LOW
| |
| DEBUG.............: an item for debugging purposes...........: DEBUG
| |
|
| |
| ==== Item priority ====
| |
|
| |
| You can use a priority number, priority letter, or priority name to
| |
| indicate a priority:
| |
| #: Abbr: Name: Default:
| |
| 0: C, !: CRITICAL: N/A
| |
| 1: H: HIGH: WARNING, TEMP, BUG, TEST, FIXME, FIXED
| |
| 2: M: MEDIUM: TODO, DONE
| |
| 3: L: LOW: HACK, COMMIT, REFERENCE, NOTE, NICE, CONSIDER
| |
| 4: D: DEBUG: DEBUG
| |
|
| |
| ==== Comment syntax ====
| |
|
| |
| Comment syntax for various programming languges is supported:
| |
| Plain text...: comment labels begin at the first character on the line
| |
| C++, etc //..: comment labels begin after '// ' (the space is important)
| |
| HTML/XML.....: comment labels are within: <nowiki><!-- --></nowiki>
| |
| Perl #.......: comment labels begin after '# ' (the space is important)
| |
| C/CSS........: comment labels are within: /* */
| |
|
| |
| === Program options ===
| |
|
| |
| ==== File-system options ====
| |
|
| |
| -p, --path=PATH process files in PATH, current directory if omitted
| |
| -f, --file=LIST process files in comma-separated LIST, relative to PATH
| |
| -i, --include=EXTENSIONS comma-separated list of included file extensions
| |
| -e, --exclude=EXTENSIONS comma-separated list of excluded file extensions
| |
| Note: excludes override includes. This is useful when
| |
| you want to exclude missing extensions ('') which
| |
| are included by default.
| |
| -s, --skip=REGEXES comma-separated list of regexes for paths to skip
| |
| -k, --keep=REGEXES comma-separated list of regexes for paths to keep
| |
| ** BE VERY CAREFUL **
| |
| Case sensitive expressions. Use '^' to match start of
| |
| path, '$' to match end of path, etc.
| |
| Note: keeps override skips
| |
|
| |
| ==== Filtering options ====
| |
|
| |
| -u, --user=[[#USER|USER]] include items for USER
| |
| -d, --date=[[#DATE|DATE]] include items for DATE
| |
| --today include items for today only (default if not debugging)
| |
| --yesterday include items for yesterday only
| |
| -t, --type=[[#TYPE|TYPE]] include items by type, will affect report order.
| |
| Duplicates are ignored.
| |
| -y, --priority=[[#PRIORITY|PRIORITY]] include items with particular PRIORITY.
| |
| --all report on all users, dates, types, and priorities.
| |
|
| |
| ==== Reporting options ====
| |
|
| |
| -a, --aggregate=[[#FIELD|FIELD]] report aggregation. Duplicates are ignored.
| |
| A heading is printed for each aggregated field.
| |
| -c, --collate=[[#FIELD|FIELD]] report sorting. Duplicates are ignored.
| |
| Default sorting uses binary comparision rather than
| |
| locale sensitive comparison which is probably what
| |
| you want. For --aggregate and --collate uppercase
| |
| FIELD sorts descending.
| |
| e.g. 'dUp' selects by date, user desc, and path
| |
| -h, --heading=[[#FORMAT|FORMAT]]
| |
| heading format options. Duplicates are ignored.
| |
| -o, --output=[[#FIELD|FIELD]]|[[#FORMAT|FORMAT]]|[[#OPTIONS|OPTIONS]]
| |
| report output options. Duplicates are ignored.
| |
| -l, --level level of heading to start at (default 2)
| |
| --na output 'N/A' when no report data
| |
| +N, --natural use locale sensitive sorting instead of binary sorting
| |
| +B, --binary use binary sorting (This is the default. Redundant? :)
| |
| +Q, --quiet disable warnings, stats, and progress on stderr
| |
| +S, --show-stats enable statistics report on stderr
| |
| -S, --hide-stats disable statistics report on stderr (default)
| |
| +P, --show-progress enable progress report on stderr
| |
| -P, --hide-progress disable progress report on stderr (default)
| |
| +O, --show-options report on user options on stderr
| |
| -O, --hide-options disable user options report (default)
| |
| +W, --show-warnings report warnings on stderr (default)
| |
| -W, --hide-warnings disable warnings
| |
|
| |
| ==== Other options ====
| |
|
| |
| --help display this help text and exit
| |
| --web-help open documentation in Firefox
| |
| --version display version information and exit
| |
| +V, --vcs parse version control (Subversion) logs
| |
| +D, --debug some handy defaults, when debugging or not
| |
| +X, --exit exit without reporting (useful with --show-stats)
| |
|
| |
| === Format specifications ===
| |
|
| |
| ==== USER ====
| |
|
| |
| USER is comma-separated list of usernames.
| |
| Use '*' for all users; '?' for current user.
| |
|
| |
| ==== DATE ====
| |
|
| |
| DATE is ISO formatted date prefix, e.g.:
| |
| '2016' for all items in 2016,
| |
| '2016-01' for items in Jan 2016,
| |
| '2016-,01,02' for items in Jan/Feb 2016,
| |
| '2016-01-,01,02' for items on 1st/2nd Jan 2106,
| |
| '2016-01-02,2016-01-04' for 2nd/4th Jan 2016.
| |
| Use '*' for all dates.
| |
|
| |
| ==== TYPE ====
| |
|
| |
| TYPE is a string of abbreviations or comma-separated list of item types.
| |
| Supported types are:
| |
| Red-flags:
| |
| w: WARNING....: something to be careful of
| |
| m: TEMP.......: a note for code that should be removed
| |
| Stuff to do:
| |
| b: BUG........: something that needs to be fixed
| |
| e: TEST.......: something that needs to be tested
| |
| t: TODO.......: something that needs to be done
| |
| h: HACK.......: something that needs to be improved
| |
| c: CONSIDER...: something to consider
| |
| Stuff that's done:
| |
| f: FIXED......: a BUG that has been fixed
| |
| d: DONE.......: something that has been done
| |
| v: COMMIT.....: a VCS commit log
| |
| Notes:
| |
| r: REFERENCE..: a reference, e.g. a URL
| |
| s: REFERENCE..:
| |
| n: NOTE.......: notes, or items without a label
| |
| g: DEBUG......: an item for debugging purposes
| |
| e.g. 'TODO, NOTE' or 'bht' for 'BUG, HACK, TODO'
| |
| Use '*' for all types.
| |
|
| |
| ==== PRIORITY ====
| |
|
| |
| PRIORITY is a comma-separeted list of priorities or a range of priorities
| |
| indicated with a dash '-' between a low and a high priority.
| |
| A priority can be indicated by a priority number, a priority letter or
| |
| abbreviation, or a priority name. Use '*' for all priorities.
| |
| Supported values are:
| |
| #: Abbr: Name...:
| |
| 0: C, !: CRITICAL
| |
| 1: H: HIGH
| |
| 2: M: MEDIUM
| |
| 3: L: LOW
| |
| 4: D: DEBUG
| |
|
| |
| ==== FIELD ====
| |
|
| |
| FIELD is a string of abbreviations or comma-separated list of fields.
| |
| Supported fields are:
| |
| u: user: select username
| |
| d: date: select date
| |
| g: long date: select date in long format
| |
| t: type: select item type
| |
| y: priority: select item priority
| |
| e: filemtime: select file modification timestamp
| |
| b: both: select path and file
| |
| p: path: select path
| |
| f: file: select file, do not prefix path.
| |
| This may not be what you want, may merge
| |
| files from different directories.
| |
| l: line: select line number
| |
| m: name: select file name
| |
| k: link: select link to file (for specific revision)
| |
| s: reference: select reference (or text if not REFERENCE)
| |
| i: initials: select Wiki initials initials (requires config)
| |
| n: new-lines: select number of new lines
| |
| o: old-lines: select number of old lines
| |
| c: line-diff: select lines difference
| |
| r: revision: select VCS revision number
| |
| w: code: select work code
| |
| x: text: select item text
| |
|
| |
| ==== FORMAT ====
| |
|
| |
| FORMAT is a string of abbreviations or comma-separated list of format
| |
| options.
| |
| Supported format options are:
| |
| U: plain-user: don't format user
| |
| D: plain-date: don't format date
| |
| T: plain-type: don't format type
| |
| Y: plain-priority: don't format priority
| |
| E: plain-filemtime: don't format filemtime
| |
| B: plain-both: don't format path/file
| |
| P: plain-path: don't format path
| |
| F: plain-file: don't format file
| |
| L: plain-line: don't format line
| |
| M: plain-name: don't format name
| |
| K: plain-link: don't format link
| |
| S: plain-reference: don't format reference
| |
| I: plain-initials: don't format initials
| |
| N: plain-new-lines: don't format new lines
| |
| O: plain-old-lines: don't format old lines
| |
| C: plain-line-diff: don't format line diff
| |
| R: plain-revision: don't format VCS revision number
| |
| W: plain-code: don't format work code
| |
| X: plain-text: don't format item text
| |
| e.g. 'UT' disables formatting for user and type values.
| |
|
| |
| ==== OPTIONS ====
| |
|
| |
| OPTIONS is a string of abbreviations or comma-separated list of report
| |
| options.
| |
| Supported report options are:
| |
| h: html: output to HTML instead of wiki text
| |
| a: table: output to HTML/wiki table instead of list
| |
| e.g. 'ha' selects HTML with tables
| |
|
| |
| === Feedback ===
| |
|
| |
| Report bugs to: [mailto:jj5@progclub.org?subject=bugslist.php jj5@progclub.org]
| |
|
| |
|
| = Specifications = | | = Specifications = |