String freeze: improve book.module help text [#97889]

Comment	File	Size	Author
#17	book-help_1.patch	5.01 KB	webchick

#15	book-help_0.patch	4.46 KB	webchick

#14	book-help.patch	4.68 KB	webchick

#11	book_help_5x_4.txt	5.22 KB	webchick
#10	book_help_5x.txt	5.22 KB	webchick
#9	book_help_5x_3.txt	5.24 KB	pwolanin
#5	book_help_5x_2.txt	5.06 KB	pwolanin
#1	book_help_5x_1.txt	4.63 KB	pwolanin
	book_help_5x_0.txt	3.3 KB	pwolanin

Comment #1

pwolanin CreditAttribution: pwolanin commented 16 November 2006 at 02:14

File	Size
book_help_5x_1.txt	4.63 KB

oops, missed a couple <p> tags inside calls to t().

Log in or register to post comments

Comment #2

pwolanin CreditAttribution: pwolanin commented 16 November 2006 at 02:19

Status:

Active

» Needs review

and there is a patch...

Log in or register to post comments

Comment #3

pwolanin CreditAttribution: pwolanin commented 16 November 2006 at 03:37

for comparison purposes, the two texts are below. Note also some changes at the level of code (not obvious in the text below), such as using a few more strong substitutions for things like the human-readable name of the content type.

ORIGINAL TEXT:

The book content type is suited for creating structured, multi-page hypertexts such as site resource guides, manuals, and Frequently Asked Questions (FAQs). It permits a document to have chapters, sections, subsections, etc. Authors with suitable permissions can add pages to a collaborative book, placing them into the existing document by adding them to a table of contents menu.

Books have additional previous, up, and next navigation elements at the bottom of each page for moving through the text. Additional navigation may be provided by enabling the book navigation block on the block administration page.

Users can select the printer-friendly version link visible at the bottom of a book page to generate a printer-friendly display of the page and all of its subsections.

Administrators can view a book outline, from which is it possible to change the titles of sections, and their weight (thus reordering sections). From this outline, it is also possible to edit and/or delete book pages. Many content types besides pages (for example, blog entries, stories, and polls) can be added to a collaborative book by choosing the outline tab when viewing the post.

MODIFIED TEXT:

The book module is suited for creating structured, multi-page hypertexts such as site resource guides, manuals, and Frequently Asked Questions (FAQs). It permits a document to have chapters, sections, subsections, etc. Authors with suitable permissions can add pages to a collaborative book, placing them into the existing document by adding them to a table of contents menu.

Book pages have navigation elements at the bottom of the page for moving through the text. These link to the previous and next pages in the book, as well as a link to up, leading to the level above in the structure. More comprehensive navigation may be provided by enabling the book navigation block on the block administration page.

Nodes of type Book page are automatically added to the book hierarchy. Users with the outline posts in books permission can also add nodes of any type to a book, placing them into the existing document by adding them to the book outline via the outline tab. This tab also provides a means for changing the position in the book's structure.

Users can select the printer-friendly version link visible at the bottom of a book page to generate a printer-friendly display of the page and all of its subsections.

Administrators can view a book outline, from which is it possible to change the titles of sections, and their weight (thus reordering sections). From this outline, it is also possible to edit and/or delete book pages. Many content types besides pages (for example, blog entries, stories, and polls) can be added to a collaborative book by choosing the outline tab when viewing the post.

Log in or register to post comments

Comment #4

drumm

he/him

NY, US

CreditAttribution: drumm commented 16 November 2006 at 07:55

Status:

Needs review

» Needs work

Mentions 'nodes'. Should be posts or content.

Log in or register to post comments

Comment #5

pwolanin CreditAttribution: pwolanin commented 16 November 2006 at 23:36

Status:

Needs work

» Needs review

File	Size
book_help_5x_2.txt	5.06 KB

improved text (patch attached):

MODIFIED TEXT:

The book module is suited for creating structured, multi-page hypertexts such as site resource guides, manuals, and Frequently Asked Questions (FAQs). It permits a document to have chapters, sections, subsections, etc. Authors with suitable permissions can add pages to a collaborative book, placing them into the existing document by adding them to a table of contents menu.

Book pages have navigation elements at the bottom of the page for moving through the text. These link to the previous and next pages in the book, as well as a link to up, leading to the level above in the structure. More comprehensive navigation may be provided by enabling the book navigation block on the block administration page.

Users can select the printer-friendly version link visible at the bottom of a book page to generate a printer-friendly display of the page and all of its subsections.

Posts of type Book page are automatically added to the book hierarchy. Users with the outline posts in books permission can also add content of any other type to a book, placing it into the existing book structure through the interface that's available by clicking on the outline tab while viewing that post.

Administrators can view a book outline, from which is it possible to change the titles of sections, or to change their weight, thus reordering sections. From this administrative interface, it is also possible to determine whether there are any orphan pages- pages that have become disconnected from the rest of the book structure.

Log in or register to post comments

Comment #6

webchick

she/they

English

Vancouver 🇨🇦

CreditAttribution: webchick commented 20 November 2006 at 22:07

Title:	improve book.module help text	» String freeze: improve book.module help text
Priority:	Normal	» Critical
Status:	Needs review	» Needs work

Cool, thanks for this, pwolanin!

Overall, the changes are a big improvement. I especially like the inclusion of the outline feature.

"as well as a link to up," reads a bit awkwardly to me. I'm wondering if we really need to further clarify what these links do, or if the old text is sufficient.
In any case though, you don't want to do things like:
```
t("as well as a link to  %up, which blah blah", array('%up' => t('up')));
```
because that moves the word "up" out of context with the rest of the sentence. So I'd go ahead and just enclose that word in <em> like the rest.
Somewhere in the sentence about the book outline, and viewing administrative interface, etc. could we put a link to the admin interface?

Log in or register to post comments

Comment #7

pwolanin CreditAttribution: pwolanin commented 20 November 2006 at 22:13

I was trying (thought not completely thoroughly) to do substitution for terms that might be modified with the locale module. That way any substitutions of terms would appear in the help page.

Log in or register to post comments

Comment #8

webchick

she/they

English

Vancouver 🇨🇦

CreditAttribution: webchick commented 20 November 2006 at 22:31

Ah, right. but the problem is that 'up' by itself has about 11 different definitions: http://m-w.com/dictionary/up

So therefore, even though it means a little extra translation, it's better to include the whole sentence so translators know you're referring specifically referring to the "up" link on book pages.

Log in or register to post comments

Comment #9

pwolanin CreditAttribution: pwolanin commented 20 November 2006 at 23:46

Status:

Needs work

» Needs review

File	Size
book_help_5x_3.txt	5.24 KB

Ok, revised text patch attached.

REVISED TEXT:

The book module is suited for creating structured, multi-page hypertexts such as site resource guides, manuals, and Frequently Asked Questions (FAQs). It permits a document to have chapters, sections, subsections, etc. Authors with suitable permissions can add pages to a collaborative book, placing them into the existing document by adding them to a table of contents menu.

Book pages have navigation elements at the bottom of the page for moving through the text. These link to the previous and next pages in the book, as well as a link labeled up, leading to the level above in the structure. More comprehensive navigation may be provided by enabling the book navigation block on the block administration page.

Users can select the printer-friendly version link visible at the bottom of a book page to generate a printer-friendly display of the page and all of its subsections.

Posts of type Book page are automatically added to the book hierarchy. Users with the outline posts in books permission can also add content of any other type to a book, placing it into the existing book structure through the interface that's available by clicking on the outline tab while viewing that post.

Administrators can view a list of all books on the book administration page. In this list there is a link to an outline page for each book, from which is it possible to change the titles of sections, or to change their weight, thus reordering sections. From this administrative interface, it is also possible to determine whether there are any orphan pages- pages that have become disconnected from the rest of the book structure.

Log in or register to post comments

Comment #10

webchick

she/they

English

Vancouver 🇨🇦

CreditAttribution: webchick commented 21 November 2006 at 00:42

File	Size
book_help_5x.txt	5.22 KB

Looks good to me!

This patch is exactly the same with two minor changes:

- Removed the %outline => t('outline') in favour of <em>outline</em> for reasons stated above w/ "up" .. now these are all consistent, with the exception of the permission name "outline posts in books" since that kind of seems logical as a separated phrase. not positive, though. Will try and find a translator-type to take a look.
- Inserted a missing newline.