String freeze: Help for help pages for modules

The help pages for the Modules need help. Good as they are, what they say is sometimes unclear, sometimes awkward, sometimes ungrammatical, and sometimes wrong.

Below, I suggest specific revisions for about half of them. (I suppose I can also do the other half.)

I have indicated links thus:

NAME_OF_LINK [link]

But the name itself is meant to be lower case.

My comments throughout are meant to be answered or deleted.

Since I worked with a plain text editor, I may have lost some formatting. This should be double-checked. And a double-check for errors concerning fact would be worthwhile.

Cordially,
O Govinda

---------------------------------------------------------------------

Home » Administer » Help

NOW: The online reference handbook might be more up-to-date
REVISED: The online reference handbook might be more up to date [delete hyphens]

NOW: [more help...]
SUGGESTION: Delete this link entirely. The text on that page is intended for module authors, not site administrators.

Glossary of Drupal terminology

-----------
Block

NOW:
A small box containing information or content placed in the left-hand or right-hand sidebar of a web page.

REVISED:

A box of content that may be placed into a certain region of a web page--for example, into a sidebar.

-----------
Moderation

NOW:
The activity of making sure a post to a Drupal site fits in with what is expected for that Drupal site.

Approved

A moderated post which has been accepted by the moderators for
publication (see published).

Waiting

A moderated post which is still being voted on to be accepted for
publication (see published).

REVISED:
Review of a post, before it is published, to make sure it fits your Drupal site.

Approved

Accepted for publication. (See published.)

Waiting

Still awaiting approval.

--------------
Public

NOW:
See published.

REVISED:
Published. [If "public" = "published," drop "See."]

--------------

Published

NOW:
A node that is viewable by everyone (see unpublished).

REVISED:
"Live." Viewable not only by administrators or moderators but by all intended viewers.

MY COMMENT: A node may be published but, because of access restrictions, not be viewable to everyone.

-------------

Role

NOW:
A classification users are placed into for the purpose of setting users' permissions.

REVISED:
A status assigned to a user, granting certain permissions. (Examples of roles are "administrator" and "unauthenticated user.")

------------

Taxonomy

NOW:
A division of a collection of things into ordered, classified groups (see taxonomy help).

REVISED:
A system for ordering things into groups. (See taxonomy help.)

------------

Unpublished

NOW:
A node that is only viewable by administrators and moderators.

REVISED:
Viewable only by administrators and moderators.

-----------

User

NOW:
A person who has an account at your Drupal site, and is logged in with that account.

REVISED:
A person who has an account on your site or who anonymously logs in.

MY COMMENT:
I'm assuming that an unauthenticated user is still a user.

--------------

Visitor

NOW:
A person who does not have an account at your Drupal site or a person who has an account at your Drupal site but is not logged in with that account. Also termed "anonymous user".

REVISED:
A person who comes to your site without having an account or who has an account but is not logged in. Also termed "anonymous user".

MY COMMENT:
Is this definition too narrow? I wonder whether people loosely use "visitor" to include even authenticated users. (In other words, do they make no distinction between "visitor" and "user"?)

-------------------------------------------------------------------------------

GENERIC ISSUES

1. The "[more help...]" link given on the help page for every module is superfluous. It does nothing. Delete.

2. No help is yet offered for the following modules:

Aggregator
Color
Drupal
Forum
Legacy
Ping
Poll
Statistics
Throttle

-------------------------------------------------------------------------------

Home » Administer » Help » Block

NOW:
The region each block appears in depends on both which theme you are using (some themes allow greater control over block placement than others), and on the settings in the block administration section.

REVISED:
The region each block appears in depends both on the settings in the block administration section and on which theme you are using (some themes allow greater control over where you can place your blocks).

NOW:
Its user visibility settings. Administrators can choose to let users decide whether to show/hide certain blocks.

REVISED:
. . . whether to show or hide certain blocks.

NOW:
Administrator defined blocks [subheading]

REVISED:
Administrator-defined blocks [add hyphen]

NOW:
Administrators can also define custom blocks. These blocks consist of a title, a description, and a body which can be as long as you wish.

REVISED:
. . . and a body, which can be as long as you wish. [add mandatory comma.]

--------------------------------------------------------------------

Home » Administer » Help » Blog

REVISED:

The blog module lets registered users maintain an online weblog, commonly known as a blog (or sometimes as an online journal or diary). Blogs consist of individual posts, time stamped and typically viewed by date, like a diary. Blogs often include links to webpages users have read (and may express opinions about).

To enable the use of blogs on your site, go to the MODULE ADMINSTRATION PAGE [link], tick the box for "Blog", and click "Save configuration" at the bottom of the page. [MY COMMENT: This instruction is essential for newbies.]

The blog module adds to your site a user blogs navigation link. (You can enable the link on the MENU ADMINISTRATION PAGE [link].) The link leads to a page that shows the most recent blog entries from all the users on your site. Also added to the navigation menu are a create a blog entry link (which takes you to a submission form) and a view personal blog link (which displays your blog entries as other people will see them). The blog module also creates a recent blog posts block, which you can enable on the BLOCK ADMINISTRATION PAGE [link].

For a user allowed to post blogs, the import module (news aggregator) will display a blog-it link next to each news item in its lists. Clicking this link takes the user to the blog submission form, with the title, a link to the item, and a link to the source into the body text already in the text box, ready for the user to add a comment or explanation. [MY COMMENT: That last sentence badly needs editing, but I can't do it, because I don't use that feature and therefore can't explain it.] This encourages people to add blog entries about things they see and hear elsewhere on the website and on your syndicated partner sites.

The blog module adds to the main navigation menu a user blogs navigation link, which takes visitors to a page that displays the most recent blog entries from all the users on your site.

For more information please read the configuration and customization handbook Blog page.

Blog administration pages
Configure permissions

----------------------------------------------------------------------------

Home » Administer » Help » Blogapi

SUGGESTION:

The name for this module may make perfect sense for developers, but for others it is jargon--and jargon tends to put people off. Would you consider giving the module a friendly name? You could ask Drupal users (or the Documentation List) to suggest one, one that might make sense to someone not technically well-informed enough to know what an API is.

Also, as long as we have the present name, is it "blogapi" or "blogAPI" or "blog API"? It should be consistent.

REVISED:

The blog API module gives your users the freedom to use the blogging tools they want to add posts to their blogs on your site.

When this module is enabled and configured you can use programs like Ecto to create and publish posts. The module supports several blogging APIs that are based on XML-RPC, such as the Blogger API, the MetaWeblog API, and most of the Movable Type API. Any desktop blogging tools or other services that support these APIs (Flickr's "post to blog," for example) should work.

This module also allows you to specify which content types can be posted with external blogging tools. So, for instance, users can post forum topics as well as blog posts. Where supported, the external blogging tools will display each content type as a separate "blog". [MY COMMENT: "Where supported"? Where what is supported--the tools or the feature?]

For more information please read the configuration and customization handbook BlogApi page.

Blog API administration pages
Blog APIs

[MY COMMENT: I don't use the Blog API module, so I'm not closely familiar with it. I've tried to make the text as clear as I can, given my limited understanding.]
-----------------------------------------------------------------------------

Home » Administer » Help » Book

A book is a set of pages tied together in sequence, perhaps with chapters, sections, subsections, and so on. You can use books for manuals, site resource guides, Frequently Asked Questions (FAQs), or whatever you'd like.

Users who have permission can collaborate in writing the book, reviewing or modifying the pages, and putting them in the right order. You can allow or disallow collaboration, to whatever extent you want.

At the bottom of book pages, Drupal automatically provides links for moving to the previous page and the next, and a link labeled up that leads to the level above in the structure. A contents page is also automatically created.

You can also provide a menu for your book by enabling the book navigation block on the BLOCK ADMINISTRATION PAGE [link]. (Users will see the menu only when viewing the book.)

On the BOOK ADMINISTRATION PAGE [link], administrators can view a list of all the books on your site. For each book there's a link to an outline, from which to edit or delete pages or sections, change their titles, or change their weight (thus putting them in a different order). When you edit a page or section, you can also move it to a different level in the hierarchy by changing the "parent" to which it belongs. So you can move things around however you like. You can also check for orphan pages (pages that have become disconnected from the rest of the book).

On the CONFIGURE PERMISSIONS PAGE [link] you can assign to various user roles the permission to create book pages or new books, and to edit their own book pages or the pages of others. You can also give permission to outline posts in books or to access books in a printer-friendly version.

When users you allow create a post of the type Book page, Drupal automatically prompts them to add their page at the level of their choice in a book, or to start a new book (by defining its "parent" as "top-level").

Users with the outline posts in books permission can also add content of any other type to a book. When viewing a post they'll see an outline tab, and by clicking it they'll come to an interface that lets them move the post into the existing book structure.

Users with permission can also generate a printer-friendly display of a book page and all its subsections by selecting the link for printer-friendly version at the bottom of the page.

For more information please read the configuration and customization handbook Book page.

Book administration pages
Configure permissions
Books
Blocks

---------------------------------------------------------------------------
Home » Administer » Help » Comment

REVISED:
The comment module creates, in effect, a discussion board for each post. When you enable this module, users can post comments to discuss a story, book page, blog post, forum topic, or whatever.

On the USER PERMISSIONS PAGE [link] you can decide which users, role by role, can see comments, post comments, or administer comments, and which users don't need to have their comments first approved. Users to whom you give permission ("administer comments") can decide whether a node they create can have comments or not.

Users can edit the last comment they have posted to a node, assuming no other comments have been posted to it since.

On the COMMENTS ADMINISTRATION PAGE [link] you (or others you empower) can decide, either for individual comments or for many at once, which comments deserve to be published, unpublished, or deleted.

On the COMMENT SETTINGS PAGE [link]

[INDENTED SECTION, WITH BULLET POINTS]

You can tailor the way comments are displayed: newest first or oldest, how many comments on each page, whether comments are shown "expanded" (with their full text) or "collapsed" (only titles and authors shown at first), and whether shown "flat" (all in date order and flush to the left) or "threaded" (comments grouped with their replies). Also, if you'd like, with each set of comments your users will see a control panel that lets them make these choices for themselves.

If you let anonymous users post comments, you can decide whether those users may or may not include their e-mail addresses in comments, or whether they must do so.

You can decide whether users can provide new subject lines for their comments. You can decide whether users must first preview their comments before posting them. And you can decide whether the form for submitting a comment appears on a separate page or below the post (and below any other comments that already exist).

[END OF INDENTED SECTION]

Comments behave like other user submissions. Filters, smileys and HTML that work in nodes will also work with comments.

The comment module provides specific features to inform site members when new comments have been posted.
[MY COMMENT: A vague mention of specific features won't do. What are these features? How do I implement them? Do they work out of the box, or do I need a user-contributed module?]

For more information please read the configuration and customization handbook Comment page.

Comment administration pages
Configure permissions
Comments

-----------------------------------------------------------------------------
Home » Administer » Help » Contact

REVISED:

The contact module helps people get in touch with one another and with whoever's running your site. Through personal contact forms users can send one another e-mail and receive replies, while their actual e-mail addresses remain private. And through site-wide contact forms users can send e-mail to your site administrators. With either form, users can specify a subject, write their message, and also have a copy of their e-mail sent to their own address.

Users (in their account settings) can turn their personal contact forms on or off. When their form is turned on, a contact tab appears in their user profile, for everyone to see. (Privileged users such as site administrators can contact even users who have turned their forms off.)

When users view their own profiles they won't see their contact tab. Only other users will see it, if it's turned on.

If both the menu module and the contact module are enabled, your MENU MANAGEMENT PAGE [link] will list your site-wide contact page (initially just called "contact") among the menu items you can show on your navigation menu. The option to show this item is disabled by default, but you can enable it. You can also place a link to your site-wide contact page among your site's primary and secondary links, or on any other menu as well. (Click "add menu item," and when you fill in the "path" field on the dialogue page just enter "contact.")

On the CONTACT ADMINISTRATION PAGE [link] you can set up "categories" of site-wide contact you'd like to receive. For example, one category might be "website feedback," and another might be "product information." For each category, you can specify whom you'd like to have receive your user's e-mail. The mail could go to one person or many. You can also specify whether or not the user will receive an automatic reply.

The SETTINGS [link] portion of the contact administration page offers you other options. You can specify what message you'd like to show on your site-wide contact page. You can limit how many times a user can contact you in an hour. And here too you can specify whether new users should have their personal contact forms turned on by default.

For more information, please read the configuration and customization handbook page for the contact module.

Contact administration pages

Configure permissions
Contact form
Menus [MY COMMENT: Note added item]

-----------------------------------------------------------------------------

Home » Administer » Help » Filter

The filter module allows you to configure formats for text input for your site. For example, you may want a filter to strip out malicious HTML from users' comments.

Despite the name "filter," the module not only lets you keep out text you don't want but also lets you enhance the text you let in. So, for example, you can use the filter module to make URLs linkable even if users enter them in an unlinked format.

When users create or edit content, they can choose between the available input formats. You can configure which formats are available to which user roles, as well as choose a default input format. You can also create new input formats. And you can configure each input format with use your choice of filters.

For more information please read the configuration and customization handbook Filter page.

Filter administration pages
Configure permissions
Input formats

-------------------------------------------------------------------------
Home » Administer » Help » Help

REVISED

The help module displays context-sensitive help.

Administrators cannot alter the help system. But module authors can make informative use of it.

For more information please read the configuration and customization handbook HELP PAGE [link].

[MY COMMENT: The text deleted--that is, all the rest of what was there--seemed written for module authors, not system admins.]

------------------------------------------------

Home » Administer » Help » Locale

NOW:
. . . replace given built-in text with text which has been customized for your site. Whenever the locale module encounters text which needs to be displayed, it tries to translate it into the currently selected language. If a translation is not available, then the string is remembered, so you can look up untranslated strings easily.

REVISED:
. . . replace given built-in text with text customized for your site. Whenever the locale module encounters text which needs to be displayed, the module tries to translate it into the currently selected language. If a translation is not available, the module remembers the string so you can look up untranslated strings easily.

NOW:
The locale module provides two options for providing translations. The first is the integrated web interface, via which you can search for untranslated strings, and specify their translations. An easier and less time-consuming method is to import existing translations for your language.

REVISED:
The locale module offers two ways to provide translations into your language. The first is to use the integrated web interface to search for untranslated strings and specify their translations. An easier and less time-consuming method is to import an existing translation.

NOW:
Translations for many languages are available for download from the translation page.

REVISED:
Translations for many languages are available for download from the TRANSLATIONS PAGE AT DRUPAL.ORG. [link]

NOW:
If an existing translation does not meet your needs, the .po files are easily edited with special editing tools. The locale module's import feature allows you to add strings from such files into your site's database.

REVISED:
If an existing translation does not meet your needs, the .po files are easily edited with special editing tools you can find on the web. [MY COMMENT: On Drupal.org?] The locale module's import feature allows you to add strings from edited files into your site's database.

-----------------------------------------------------

Home » Administer » Help » Menu

REVISED:

Menus are sets of links (menu items) used to navigate a website. The menu module lets you control and customize the powerful menu system that comes with Drupal. Menus appear mainly as hierarchical lists of links, shown by using Drupal's BLOCKS [link] feature. By default, new menu items are placed inside a built-in menu labelled Navigation, but you can also create new menus.

Drupal themes generally provide out-of-the-box support for two menus, commonly labelled primary links and secondary links. These two sets of links are usually displayed in each page's header or footer (whichever the theme may specify). You can make any menu the one for primary or secondary links via the MENU SETTINGS PAGE [link].

Menu administration tabs:

[BEGIN INDENTED SECTION, WITH BULLET POINTS]

On the administer menu page, administrators can "edit" to change the title, description, parent or weight of a menu item. Under the "operations" column, click "enable" or "disable" to toggle a menu item on or off. Only menu items that are enabled are displayed. You can also delete menus items. But the default menu items generated by the menu module cannot be deleted, only disabled.

To create a new menu, use the "add menu" tab. Once you submit a title for your new menu, that title will appear towards the top of the administer menu page. Under that title you will see links by which you can edit the menu, delete it, or add to it new items.

[DISPENSE WITH THE BULLET FOR THIS PARAGRAPH] When you create a new menu and give it a name, Drupal automatically creates a block for it with the same name. For your menu to appear to your users, you must go to the BLOCKS ADMINISTRATION PAGE [link] and enable that block. That page, too, lets you choose where on each page your block will appear. And the configure link given for each block lets you further choose which pages your block will appear on, to whom, and under which circumstances.

To create a new link in any menu, click the "add menu item" tab at the top of the page (or the "add item" tab beneath the name of any menu). You'll then see a dialogue page. There, under "parent item," you can choose where within the existing menu structure you want your new item to appear. Choose the name of a top-level item or any item beneath, and in the menu your item will be placed below it.

[END INDENTED SECTION]

On the CONFIGURE PERMISSIONS PAGE [link] you can decide who is allowed to administer menus on your site and who can administer blocks (thereby making menus visible). When users who have permission to administer menus create content, they can add new menu items for that content "on the fly."

For more information please read the configuration and customization handbook Menu page.

Menu administration pages

Menus
Blocks [MY COMMENT: NOTE this added item]
Configure permissions

[END]