Mercurial Repository: p/roundup/code: doc/reference.txt comparison

comparison doc/reference.txt @ 7868:6c219034bf31

doc: vale corrections and some rewriting.

author	John Rouillard <rouilj@ieee.org>
date	Sun, 07 Apr 2024 23:16:58 -0400
parents	1774fdf2010a
children	d4f6ba8e3c1e

comparison

equal deleted inserted replaced

-:1774fdf2010a
+:6c219034bf31
 The utils variable
 ~~~~~~~~~~~~~~~~~~
 This is implemented by the
-``roundup.cgi.templating.TemplatingUtils`` class, which may be extended
+``roundup.cgi.templating.TemplatingUtils`` class. New methods can
-with additional methods by extensions_.
+be added to the variable by using extensions_.
 .. table::
 :class: valign-top
 =============== ========================================================
 values from the supplied dictionary.
 html_quote      quote some text as safe in HTML (ie. <, >, ...)
 html_calendar   renders an HTML calendar used by the
 		  ``_generic.calendar.html`` template (itself invoked by
 		  the popupCalendar DateHTMLProperty method
-readfile        read Javascript or other content in an external
+readfile        read JavaScript or other content in an external
 file into the template.
 url_quote       quote some text as safe for a URL (ie. space, %, ...)
 =============== ========================================================
 Additional info can be obtained by starting ``python`` with the
 :class: valign-top
 ========= ==============================================================
 Parameter  Usage
 ========= ==============================================================
-sequence  a list of HTMLItems
-size      how big to make the sequence.
-start     where to start (0-indexed) in the sequence.
 end       where to end (0-indexed) in the sequence.
 orphan    if the next batch would contain less items than this value,
 	    then it is combined with this batch
 overlap   the number of items shared between adjacent batches
+sequence  a list of HTMLItems
+size      how big to make the sequence.
+start     where to start (0-indexed) in the sequence.
 ========= ==============================================================
 All of the parameters are assigned as attributes on the batch object. In
 addition, it has several more attributes:
 :class: valign-top
 =============== ========================================================
 Attribute       Description
 =============== ========================================================
-start           indicates the start index of the batch. *Unlike
-		  the argument, is a 1-based index (I know, lame)*
 first           indicates the start index of the batch *as a 0-based
 		  index*
 length          the actual number of elements in the batch
+start           indicates the start index of the batch. *Unlike
+		  the argument, is a 1-based index (I know, lame)*
 sequence_length the length of the original, unbatched, sequence.
 =============== ========================================================
 And several methods:
 tal:repeat="keyword batch" tal:content="keyword/name">
 keyword here</td>
 </tr>
 </table>
-... which will produce a table with four columns containing the items of
+will produce a table with four columns containing the items of
 the "keyword" class (well, their "name" anyway).
 Translations
 ~~~~~~~~~~~~
 <tal:x tal:replace="python:request.client.setHeader(
 'Content-Type', 'application/atom+xml'
 )"/>
-will set the Content-Type header. The header name is case sensitive,
+will set the ``Content-Type`` header. The header name is case sensitive,
 so use capital letters as shown. If you don't you end up with multiple
 Content-Type definitions returned to the browser.
 Displaying Properties
 ---------------------
 Properties appear in the user interface in three contexts: in indices,
 in editors, and as search arguments. For each type of property, there
 are several display possibilities. For example, in an index view, a
-string property may just be printed as a plain string, but in an editor
+string property may just be printed as a plain string. In an editor
 view, that property may be displayed in an editable field.
 Index Views
 -----------
 @filters=status,keyword&
 @columns=title,status,fixer
 The index view is determined by two parts of the specifier: the layout
 part and the filter part. The layout part consists of the query
-parameters that begin with colons, and it determines the way that the
+parameters that begin with the '@' character, and it determines
-properties of selected items are displayed. The filter part consists of
+the way that the properties of selected items are displayed. The
-all the other query parameters, and it determines the criteria by which
+filter part consists of all the other query parameters, and it
-items are selected for display. The filter part is interactively
+determines the criteria by which items are selected for
-manipulated with the form widgets displayed in the filter section. The
+display. The filter part is interactively manipulated with the
-layout part is interactively manipulated by clicking on the column
+form widgets displayed in the filter section. The layout part is
-headings in the table.
+interactively manipulated by clicking on the column headings in
+the table.
 The filter part selects the union of the sets of items with values
 matching any specified Link properties and the intersection of the sets
-of items with values matching any specified Multilink properties.
+of items with values matching any specified MultiLink properties.
 The example specifies an index of "issue" items. Only items with a
-"status" of either "unread" or "in-progress" or "resolved" are
+"status" of either "unread", "in-progress" or "resolved" are
 displayed, and only items with "keyword" values including both "security"
 and "ui" are displayed. The items are grouped by priority arranged in
 ascending order and in descending order by status; and within
 groups, sorted by activity, arranged in descending order. The filter
 section shows filters for the "status" and "keyword" properties, and the
 ``@action`` variable. The "search" action:
 - sets up additional filtering, as well as performing indexed text
 searching
 - sets the ``@filter`` variable correctly
-- saves the query off if ``@query_name`` is set.
+- saves the query to the user's query list if ``@query_name`` is set.
 The search page should lay out any fields that you wish to allow the
 user to search on. If your schema contains a large number of properties,
 you should be wary of making all of those properties available for
 searching, as this can cause confusion. If the additional properties are
 ============ =============================================================
 Argument     Description
 ============ =============================================================
 @query_name  if supplied, the index parameters (including @search_text)
-	       will be saved off as a the query item and registered against
+	       will be saved as a the query item and registered against
 	       the user's queries property. Note that the *classic* template
 	       schema has this ability, but the *minimal* template schema
 	       does not.
 ============ =============================================================
 </tr>
 <tr>
 <th>Change Note</th>
 <td colspan="3">
-<textarea name=":note" wrap="hard" rows="5" cols="60"></textarea>
+<textarea name="@note" wrap="hard" rows="5" cols="60"></textarea>
 </td>
 </tr>
 <tr>
 <th>File</th>
-<td colspan="3"><input type="file" name=":file" size="40"></td>
+<td colspan="3"><input type="file" name="@file" size="40"></td>
 </tr>
 <tr>
 <td>&nbsp;</td>
 <td colspan="3" tal:content="structure context/submit">
 </table>
 When a change is submitted, the system automatically generates a message
 describing the changed properties. As shown in the example, the editor
-template can use the ":note" and ":file" fields, which are added to the
+template can use the "@note" and "@file" fields, which are added to the
 standard changenote message generated by Roundup.
 Form values
 :::::::::::
 We have a number of ways to pull properties out of the form in order to
 meet the various needs of:
 1. editing the current item (perhaps an issue item)
-2. editing information related to the current item (eg. messages or
+2. editing information related to the current item (e.g. messages or
 attached files)
-3. creating new information to be linked to the current item (eg. time
+3. creating new information to be linked to the current item (e.g. time
 spent on an issue)
 In the following, ``<bracketed>`` values are variable, ":" may be one of
 ":" or "@", and other text ("required") is fixed.
 ``<classname>-<N>:<propname>``
 property on the Nth new item of classname (generally for creating new
 items to attach to the current item)
-Once we have determined the "propname", we check to see if it is one of
+Once we have determined the "propname", check to see if it is one of
 the special form values:
 ``@required``
 The named property values must be supplied or a ValueError will be
 raised.
 Defining new web actions
 ------------------------
-You may define new actions to be triggered by the ``@action`` form variable.
+You may define new actions triggered by the ``@action`` form variable.
-These are added to the tracker ``extensions`` directory and registered
+These defined in the tracker's ``extensions`` directory and registered
 using ``instance.registerAction``.
-All the existing Actions are defined in ``roundup.cgi.actions``.
+All the pre-existing Actions are defined in ``roundup.cgi.actions``.
 Adding action classes takes three steps; first you `define the new
 action class`_, then you `register the action class`_ with the cgi
-interface so it may be triggered by the ``@action`` form variable.
+interface so it can be triggered by the ``@action`` form variable.
 Finally you `use the new action`_ in your HTML form.
 See `setting up a "wizard" (or "druid") for controlled adding of
 issues
 <customizing.html#setting-up-a-wizard-or-druid-for-controlled-adding-of-issues>`_ for an example.
 override the content type indicated to the user by calling ``setHeader``::
 self.client.setHeader('Content-Type', 'text/csv')
 This example indicates that the value sent back to the user is actually
-comma-separated value content (eg. something to be loaded into a
+comma-separated value content (i.e. something to load into a
 spreadsheet or database).
 8-bit character set support in Web interface
 --------------------------------------------
-The web interface uses UTF-8 default. It may be overridden in both forms
+The web interface uses UTF-8 default. It may be overridden in
-and a browser cookie.
+both forms and a browser cookie. In general, the UTF-8 standard
+should work with all modern browsers. You shouldn't have to
+make any modifications from this section.
 - In forms, use the ``@charset`` variable.
 - To use the cookie override, have the ``roundup_charset`` cookie set.
 In both cases, the value is a valid charset name (eg. ``utf-8`` or
 ``kio8-r``).
 Inside Roundup, all strings are stored and processed in utf-8.
 Unfortunately, some older browsers do not work properly with
 utf-8-encoded pages (e.g. Netscape Navigator 4 displays wrong
-characters in form fields).  This version allows one to change
+characters in form fields).  Roundup allows one to change
-the character set for http transfers.  To do so, you may add
+the character set for http transfers. To do so, you may add
 the following code to your ``page.html`` template::
 <tal:block define="uri string:${request/base}${request/env/PATH_INFO}">
 <a tal:attributes="href python:request.indexargs_url(uri,
 {'@charset':'utf-8'})">utf-8</a>
 />
 The charset is also sent in the http header.
 Debugging Trackers
 ==================
 There are three switches in tracker configs that turn on debugging in
 Roundup:

Mercurial > p > roundup > code

comparison doc/reference.txt @ 7868:6c219034bf31