GNOME Bugzilla – Bug 668110
Rewrite documentation
Last modified: 2013-08-03 08:48:17 UTC
The documentation still uses the name Epiphany.
Created attachment 211365 [details] [review] Replaced the occurance of Epiphany with Web The document didn't make the change from Epiphany to Web. The patch corrects the error.
I don't see much sense in updating this currently, as the complete manual is extremely outdated and wrong in many places. Fixing this would not really help, rewriting would...
*** Bug 674638 has been marked as a duplicate of this bug. ***
Is a rewrite of the documentation planned?
(In reply to comment #4) > Is a rewrite of the documentation planned? Yes, as soon as we find a volunteer. :-)
*** Bug 678480 has been marked as a duplicate of this bug. ***
Created attachment 217864 [details] [review] help C only Mallad - First version
I did work on a first revamp. Not complete, and the doc design might be reviewed, but I hope a commit to help reviewing. I can still send the doc as an archive if someone wants to yelp it before. Most of it comes from the old documentation, with obsolete parts deleted and syntax ported to mallard. (Also, I have an issue with jhbuild webkit, which means I did not perform any test apart from navigating the doc itself.)
Created attachment 219077 [details] [review] Manual building with autotools This git commit adds help subdir and amends buil process so doc is properly installed. I shall generate another commit to re-add Help Buttons.
Created attachment 219145 [details] [review] Readd F1 shortcut and Help button This commit simply put back the Help Button and F1 to display help.
With last commit the doc can be tested easily. I'm surprised but 'jhbuild run epiphany' then F1 displays the right documentation (new one) and not the system wide installed one. I hope it can makes review easier.
Comment on attachment 211365 [details] [review] Replaced the occurance of Epiphany with Web As we know, this is obsolete now. Reviewing the big patch now.
(In reply to comment #11) > With last commit the doc can be tested easily. > > I'm surprised but 'jhbuild run epiphany' then F1 displays the right > documentation (new one) and not the system wide installed one. I hope it can > makes review easier. Hrm, odd, actually the opposite happens for me. I get the system wide one.
(In reply to comment #13) > Hrm, odd, actually the opposite happens for me. I get the system wide one. I don't know why, but confirm i get the jhbuid one. On the worst case, below command will display the manual, $ yelp /somewhere/share/gnome/help/epiphany/C/ (where "somewhere" stands for "jhbuild installation folder")
CCing Shaunm since he mentioned there will be a doc sprint next month and it's probably a good idea that someone with more experience than myself has a look at this too. I can read it and make sure it's technically accurate but I'm not a documentation expert!
(In reply to comment #14) > I don't know why, but confirm i get the jhbuid one. > On the worst case, below command will display the manual, > > $ yelp /somewhere/share/gnome/help/epiphany/C/ > > (where "somewhere" stands for "jhbuild installation folder") Right! Reading it now. The patch itself seems sensible, and the second one for the code is also just fine. So I think we just need to get the OK from the doc guys and this should be good to go for 3.6. Thanks for keeping at it!
Review of attachment 219077 [details] [review]: First of all, thanks for your hard work on this! I did not read all files, but many comments I made also apply to other places in your patch. Note that I don't have Epiphany 3.5 around on this machine, so I did NOT check if all the steps are really correct, and I did not comment on the structure of the docs, so this still needs to be done. I only comment on syntax etc, and please take my comments with a grain of salt and don't get demotivated or so just because I'm interested in really good user docs and therefore am a bit picky. :) I'll start with pasting the errors that I got when applying the patch: $:andre\> git am 0001-Add-Epiphany-Manual-see-bug-https-bugzilla.gnome.org.patch Applying: Add Epiphany Manual , see bug https://bugzilla.gnome.org/show_bug.cgi?id=674047 /opt/git-gnome/epiphany/.git/rebase-apply/patch:109: space before tab in indent. $(NULL) /opt/git-gnome/epiphany/.git/rebase-apply/patch:213: trailing whitespace. <td><p>To Do This</p></td> <td><p>Press This</p></td> /opt/git-gnome/epiphany/.git/rebase-apply/patch:218: trailing whitespace. <td><p>Select a bookmark or topic</p></td> <td><p>Click on the bookmark or topic.</p></td> /opt/git-gnome/epiphany/.git/rebase-apply/patch:221: trailing whitespace. <td><p>Select a group of contiguous bookmarks</p></td> <td><p>Press-and-hold <key>Shift</key>. Select the first bookmark in the group, then select the last bookmark in the group.</p></td> /opt/git-gnome/epiphany/.git/rebase-apply/patch:224: trailing whitespace. <td><p>Select multiple bookmarks</p></td> <td><p>Press-and-hold <key>Ctrl</key>. Select the bookmarks one by one.</p></td> warning: squelched 82 whitespace errors warning: 87 lines add whitespace errors. Also, check for consistent use of page, site, website, web site, web page, webpage, etc. ::: help/C/ephy-bookmarks-management.page @@ +53,3 @@ + + <section id="bookmarks-list"><title>Quickly access bookmarks</title> + <p>Bookmarks list : click on the window gear menu, and select bookmarks to display the list of topics and bookmarks. Click on a bookmark to go to this page.</p> "page" confused me a bit. Maybe "website" or "address"? Not sure why there is a "Bookmarks list : " at the start either. What does that mean? A definition for that term? That I should be in that window/dialog already for these steps? @@ +58,3 @@ + + <section id="bookmarks-window"><title>Bookmarks Window</title> + <p>The primary way to access bookmarks is the bookmarks window. To Open the Bookmarks Window, simply select <guiseq><gui>Web Menu</gui><gui>Bookmarks</gui></guiseq>. It will open the bookmarks window (or display this window if already opened).</p> Capitalization typo: "Open". I would remove "simply" here. @@ +62,3 @@ + </section> + + <section><title>Create Bookmark</title> Either "Create Bookmarks" or "Create a Bookmark" @@ +66,3 @@ + <list> + <item> + <p>Browser Window : </p> " : " should be ":", also in other places. @@ +67,3 @@ + <item> + <p>Browser Window : </p> + <p>To bookmark the currently viewed page, choose <guiseq><gui>Gear Button</gui><gui>Bookmarks</gui><gui>Add Bookmark...</gui></guiseq>.</p> You sometimes write <gui>Web Menu</gui>, sometimes <gui>Gear Button</gui>, sometimes <gui>Application menu</gui>. I don't have a Epiphany 3.5 build handy right now so I'm not sure if it isn't all the same, but checking for consistent terminology again would be good. Maybe I'm completely wrong here though. :) @@ +88,3 @@ + </tr> + <tr> + <td><p>Select a group of contiguous bookmarks</p></td> <td><p>Press-and-hold <key>Shift</key>. Select the first bookmark in the group, then select the last bookmark in the group.</p></td> Not sure why Press-and-hold has hyphens here and in other palces.. @@ +94,3 @@ + </tr> + <tr> + <td><p>Select all bookmarks in a topic.</p></td> <td><p> Choose <gui>Edit</gui><gui>Select All</gui>.</p></td> "<p> Choose" should be "<p>Choose", also in other places. @@ +102,3 @@ + + <section><title>To Open a Bookmark in a New Window or Tab</title> + <p>To open a bookmark in a new window perform the following steps: Select the bookmark that you want to open. Choose <gui>File</gui><gui>Open in New Window</gui>. Alternatively, choose <gui>Open in New Window</gui> from the context menu of the bookmark. To open a bookmark in a new tab perform the following steps: Select the bookmark that you want to open. Choose <gui>File</gui><gui>Open in New Tab</gui>. Alternatively, choose <gui>Open in New Tab</gui> from the context menu of the bookmark. </p> Shouldn't this be a list instead? @@ +105,3 @@ + </section> + + <section><title id="add-b ookmark">To Add a Bookmark to a Topic</title> Broken whitespace in id. @@ +133,3 @@ + so that the currently selected topics come first. + Choose each topic from which you wish to remove this bookmark, simply by + selecting it, and press <gui>Close</gui> when you have finished. Assuming that this is a button, it should have <gui style="button">. Also in other places. @@ +170,3 @@ + + <section><title>To Copy the Address of a Bookmark</title> + <p>To copy the address of a bookmark perform the following steps: Select the bookmark. Choose <gui>Edit</gui><gui> Copy Address</gui>. Alternatively, choose <gui>Copy Address</gui> from the bookmark's context menu.</p> I assume that "<gui>Edit</gui><gui> Copy Address</gui>" misses a <guiseq> around. ::: help/C/ephy-bookmarks-smart-bookmarks.page @@ +81,3 @@ + + <section><title>Bookmarked Searches Archive</title> + <p>An archive containing lots of Bookmarked Searches is available at the <link href="http://galeon.sourceforge.net/bookmarks/">Galeon</link> web site.</p> No, there is not. If you go to http://galeon.sourceforge.net/bookmarks/browse.php you will get an "Un able to connect to database" [sic!] error. ::: help/C/ephy-content-print.page @@ +7,3 @@ + <link type="guide" xref="index#content"/> + <license><p>GNU Free Documentation License (GFDL), Version 1.1</p></license> + <desc>Print the page</desc> maybe "to paper"? Or does it also support PDF? :) @@ +51,3 @@ + + <title>Print a page</title> + <p>Use the <guiseq><gui>gear button</gui><gui>Print</gui></guiseq> item to print a page.</p> Isn't this a list of items? @@ +54,3 @@ + <p>Select the name of the printer in the <gui>Printer</gui> list or select <gui>Print to File</gui> to print to a file.</p> + <p>In the <gui>Print Pages</gui> section, choose <gui>All</gui> to print the entire web page, <gui>Current</gui> to print the currently selected page only or <gui>Range</gui> to print the range of pages that you specify.</p> + <p>To set up the paper size, print layout, and printer margins, choose <gui>Page Setup</gui> tab.. </p> Typo: Choose *the* tab. Plus you end with ".. " while it should be a fullstop only. @@ +56,3 @@ + <p>To set up the paper size, print layout, and printer margins, choose <gui>Page Setup</gui> tab.. </p> + <list> + <item><p>Paper Size : Size of the sheets in your printer. Two often used sizes are A4 and Letter.</p></item> "Paper Size" should be encapsulated by <gui>. Not sure if this really needs to be covered here - this is all system-wide stuff that is hopefully covered under http://library.gnome.org/users/gnome-help/3.4/printing.html already. In general you should be able to link to the desktop help by using syntax like <link href="ghelp:gnome-help#printing"> @@ +57,3 @@ + <list> + <item><p>Paper Size : Size of the sheets in your printer. Two often used sizes are A4 and Letter.</p></item> + <item><p>Orientation Defines whether the top of the page is the short (portrait) or long (landscape) edge of the paper.</p></item> "Orientation" should be encapsulated by <gui>. @@ +59,3 @@ + <item><p>Orientation Defines whether the top of the page is the short (portrait) or long (landscape) edge of the paper.</p></item> + </list> + <p>With print preview, you can see how a page will look once it has been printed. To print preview the current page, choose <gui>Print Preview</gui>.</p> With? Maybe "in". Also, I don't consider sentences like "To print preview the current page, choose <gui>Print Preview</gui>." useful. It's a bit like "Click Save to Save" or "Walk to the Shop to walk to the shop". :) ::: help/C/ephy-content-search.page @@ +50,3 @@ + </info> + + <title>Look for some text</title> I would maybe use "Find" here and "on a website". @@ +54,3 @@ + + <list> + <item><p>click <guiseq><gui>Gear button</gui><gui>Search</gui></guiseq> (or type <keyseq><key>Ctrl</key><key>F</key></keyseq> ) ,to display the <gui>Find</gui> dialog at the bottom of the browser window.</p></item> Missing capitalization of "click". Spelling: "/keyseq> ) ,to " should be "/keyseq>), to " Markup for buttons like <gui>Gear button</gui> can become <gui style="button">, probably also in other places. @@ +55,3 @@ + <list> + <item><p>click <guiseq><gui>Gear button</gui><gui>Search</gui></guiseq> (or type <keyseq><key>Ctrl</key><key>F</key></keyseq> ) ,to display the <gui>Find</gui> dialog at the bottom of the browser window.</p></item> + <item><p>Type the string that you want to find, in the Find field.</p></item> Find should probably be encapsulated in <gui> tags? @@ +58,3 @@ + </list> + + <p>To only find occurrences of the string that match the case of the text that you type, select <gui>Case sensitive</gui>. </p> Plenking here and in many many other places: "</gui>. </p>" should be "</gui>.</p>" without the whitespace, for the sake of consistent strings and less work for translators. @@ +60,3 @@ + <p>To only find occurrences of the string that match the case of the text that you type, select <gui>Case sensitive</gui>. </p> + <p>Press <gui>Find Next</gui> to search the page for the first occurrence of the string. If the string is found, the cursor is moved to the string, and the string is selected. To find the next occurrence of the string, press <gui>Find Next</gui>. To find the previous occurrence of the string, press <gui>Find Previous</gui>.</p> + <note><p>When <app>Web</app> has reached the end of the page, the search will be continued from the beginning of the page. The message Wrapped will be shown in the search bar.</p></note> I don't understand "The message Wrapped will be shown". "The message will be shown wrapped"? "The message <gui>Wrapped</gui> will be shown"? ::: help/C/ephy-content-source.page @@ +7,3 @@ + <link type="guide" xref="index#content"/> + <license><p>GNU Free Documentation License (GFDL), Version 1.1</p></license> + <desc>Source</desc> A single noun is rather unhelpful. Maybe "View the Source Code of a Website" or so - the verb helps understanding "what" to do here... @@ +51,3 @@ + + <title>Source</title> + <p>To view the source code of a page, choose <guiseq><gui>Gear Button</gui><gui>Page Source</gui></guiseq>. The source will be displayed in your default text editor.</p> Text editor is at least not eh case in 3.2 that is on this machine, but hopefully this is correct in 3.5. :) ::: help/C/ephy-downloads.page @@ +8,3 @@ + <link type="guide" xref="toolbar#links"/> + <license><p>GNU Free Documentation License (GFDL), Version 1.1</p></license> + <desc>Download any file you want</desc> I don't consider this <desc> helpful. Feels like an advertisement for illegal MP3 files or so. @@ +52,3 @@ + + <title>Using the Download Manager</title> + <p><key>Shift</key> Click on a link, image or page will cause it to be downloaded to your default downloads folder.</p> "<key>Shift</key> Click" sounds weird. Maybe "Click on a link while pressing <key>Shift</key>"? @@ +68,3 @@ + <item><p>To pause a download, select its entry in the download manager and press <gui> +Pause</gui>.</p></item> + <item><p>To resume a download, select its entry in the download manager and press <gui> Resume</gui>.</p></item> Plenking: <gui> Resume</gui> should be <gui>Resume</gui> ::: help/C/ephy-extension-adblock.page @@ +8,3 @@ + <link type="guide" xref="index#content"/> + <license><p>GNU Free Documentation License (GFDL), Version 1.1</p></license> + <desc>Block Adds</desc> Adds should be Advertisements instead. @@ +51,3 @@ + </info> + + <title>AddBlock</title> It's AdBlock. @@ +52,3 @@ + + <title>AddBlock</title> + <p>Addblock allows you not to display adds while surfing on the web.</p> "adds" should be "advertisements". Currently this page is a placeholder / stub it seems. :) ::: help/C/ephy-extension-html5.page @@ +8,3 @@ + <link type="guide" xref="common-issues"/> + <license><p>GNU Free Documentation License (GFDL), Version 1.1</p></license> + <desc>View video on Youtube</desc> This is misleading. The <title> says "Watch HTML5 videos". In general. Now the <desc> only talks about one single website on the internet, called youtube.com. @@ +52,3 @@ + + <title>Watch HTML5 videos</title> + <p></p> Okay, this is a placeholder / stub too. Might be helpful later (in order to quickly identify stubs) if you used TODO entries, or markup like <revision pkgversion="3.5" date="2012-07-19" status="stub"/> but up to you. ::: help/C/ephy-history.page @@ +52,3 @@ + + <title>History</title> + <p>Epiphany collects history information about locations that are visited by you. This information is stored in a database and can then be accessed later. As you type in the location bar of the main window, <app>Web</app> searches for matches in the title or address of the locations stored in the history and the bookmark databases. Matches are shown in a list below the location bar.</p> Is it relevant for the user that it is in a database? @@ +53,3 @@ + <title>History</title> + <p>Epiphany collects history information about locations that are visited by you. This information is stored in a database and can then be accessed later. As you type in the location bar of the main window, <app>Web</app> searches for matches in the title or address of the locations stored in the history and the bookmark databases. Matches are shown in a list below the location bar.</p> + <note><p>You can manage history by opening the history window. This window allows you to search the history, and delete locations you do not want to revisit later.</p></note> "the" or "your" history maybe? There is only one for each user... @@ +69,3 @@ + <list> + <item><p>Select the history link that you want to delete. </p></item> + <item><p>Choose <guiseq><gui>Edit</gui><gui>Delete</gui></guiseq>.Alternatively, choose <gui>Delete</gui> from the context menu of the history link.</p></item> Typo: Missing space after fullstop. @@ +76,3 @@ + <p>You can type into the search entry in the history window. In case any matches are found in the history database, they are shown in a list below. These matches can then be opened in a new window, a new tab or the link address can be copied for pasting in any other +application. </p> + <p>Alternatively, anything you enter in the address entry of the <app>Web</app> window is matched against the history database, and shown in a drop down list alongwith other matches from the bookmarks database. </p> Typo: alongwith @@ +91,3 @@ + <list> + <item><p>Select the history link.</p></item> + <item><p>Choose <guiseq><gui>File</gui><gui>Add Bookmark...</gui></guiseq>. Alternatively, choose <gui>Add Bookmark...</gui> from the context menu of the history link. </p></item> Plenking: Whitespace in front of </p>. ::: help/C/ephy-privacy-certificates.page @@ +58,3 @@ + <item><p>An unlocked padlock : Indicates that this site is insecure.</p></item> + <item><p>A locked padlock : Indicates that this site is secure.</p></item> + <item><p>A broken padlock Indicates that some parts of this page are secure, and others are not. You should consider the page as a whole to be insecure.</p></item> Missing a colon as the two entries before had one. ::: help/C/ephy-privacy-clean.page @@ +50,3 @@ + + <title>Clearing your personal data</title> + <p><app>Web</app> let you clear all your personal data it remembered in an easy way.</p> lets instead of let. Let's please drop the "in an easy way" - it's marketing speech that only clutters the text and does not help. @@ +51,3 @@ + <title>Clearing your personal data</title> + <p><app>Web</app> let you clear all your personal data it remembered in an easy way.</p> + <p>The Clear All dialog, which can be accessed by clicking on the <gui>Clear All...</gui> on the bottom right corner of the Personal Data Manager, let you specify the items of your personal data you want to clean. For details see: <xref link="cookies"/>, <gui> around "Clear All"? But how to access the "Personal Data Manager" first? @@ +52,3 @@ + <p><app>Web</app> let you clear all your personal data it remembered in an easy way.</p> + <p>The Clear All dialog, which can be accessed by clicking on the <gui>Clear All...</gui> on the bottom right corner of the Personal Data Manager, let you specify the items of your personal data you want to clean. For details see: <xref link="cookies"/>, +<xref linkend="passwords"/> and <xref linkend="history"/>. At least in Yelp 3.2 these links are not shown at all, but maybe this works in 3.4/3.5. Sure you want to use linkend instead of link? I must admit I don't know what the difference is... @@ +53,3 @@ + <p>The Clear All dialog, which can be accessed by clicking on the <gui>Clear All...</gui> on the bottom right corner of the Personal Data Manager, let you specify the items of your personal data you want to clean. For details see: <xref link="cookies"/>, +<xref linkend="passwords"/> and <xref linkend="history"/>. +Note that the operation is not undoable, and by clicking on <gui>Clear</gui> Whou, "not undoable" made me think for a while before understanding the two negations. Maybe "Note that you cannot revert the action". "Operation" fells pretty techy anyway. ::: help/C/ephy-privacy-cookies.page @@ +61,3 @@ + <item><p>The content of the cookie.</p></item> + <item><p>The path within the domain for which the cookie is valid. </p></item> + <item><p>When Any type of connection, the cookie can be sent to any server. </p></item> The sentence structure needs improvement and this misses <gui> markup. Maybe something like "When choosing <gui>Any" Same for the next line. Also here and in other places you have a whitespace in front of </p> that shouldn't be there. @@ +63,3 @@ + <item><p>When Any type of connection, the cookie can be sent to any server. </p></item> + <item><p>When Encrypted connections only, the cookie will only be sent to secure servers. </p></item> + <item><p>The date and time at which the cookie is no longer valid.</p></item> This sentence no verb. :) ::: help/C/ephy-privacy-passwords.page @@ +53,3 @@ + <title>Manage the passwords</title> + <p>Many web sites require you to log in using a username and password to gain access to some or all of the site. <app>Web</app> can remember the passwords for you so that you can quickly login in future.</p> + <p>In Personal Data Manager, you can view the sites for which passwords have been stored, and delete them. To delete passwords, select all the entries you want to delete, and press the <gui>Remove</gui> button. The password content is normally hidden to protect your privacy. You can use the <gui>Show passwords</gui> toggle to reveal previously saved passwords.</p> But how to access "Personal Data Manager"? Plus "PDM" should probably have <gui> around... ::: help/C/ephy-setup-privacy.page @@ +8,3 @@ + <link type="guide" xref="cookies"/> + <license><p>GNU Free Documentation License (GFDL), Version 1.1</p></license> + <desc>Control privacy behaviour</desc> Should be "behavior" here and in other places, as we use American English by default. @@ +52,3 @@ + + <title>Amend privacy settings</title> + <p><app>Web</app> allows you to configure a number of features which allow you to restrict what web pages can do :</p> Remove double whitespace and whitespace in front of the colon. ::: help/C/ephy-setup-search-engine.page @@ +15,3 @@ + </info> + + <title>Define default Search Engine</title> Define a, or the, maybe? Inconsistent capitalization. @@ +16,3 @@ + + <title>Define default Search Engine</title> + <p>The search engine can be changed using the org.gnome.Epiphnay keyword-search-url value, eg to use Duck Duck Go as a default engine : </p> Typo: Epiphnay. It's not clear to me which value mentioning some hard-to-read "value" brings me here. Why would I care about details if I just want to change my default search engine? :) Not clear how and where to enter the command (it's in a terminal window). "Duck Duck Go" is a name and should be in markup I guess. Whitespaces in front and after the colon should be removed, also in other places. @@ +18,3 @@ + <p>The search engine can be changed using the org.gnome.Epiphnay keyword-search-url value, eg to use Duck Duck Go as a default engine : </p> +<p><cmd>gsettings set org.gnome.Epiphany keyword-search-url http://duckduckgo.com/?q=%s</cmd></p> + <p>The principle is the same than <link xref="smart-bookmarks">smart bookmarks</link></p>. The full stop is outside of the markup. Should be between </link> and </p>. ::: help/C/ephy-setup.page @@ +52,3 @@ + <title>Setting Your Preferences</title> + <p>You can customize <app>Web</app> to suit your personal needs by using the Preferences +dialog which can be accessed by selecting <gui>Edit</gui><gui>Preferences</gui></p> Missing <guiseq> here. Plus "Preferences" should probably have <gui> too. ::: help/C/ephy-toolbar.page @@ +7,3 @@ + <link type="guide" xref="index#navigation"/> + <license><p>GNU Free Documentation License (GFDL), Version 1.1</p></license> + <desc>Enter URL, go back and forth or simply search</desc> "Enter an URL"? Maybe "web address" is better here though, "URL" is a very techy term. @@ +61,3 @@ + + <section><title>Go back and forth</title> + <p>You can use the toolbar to navigate through your web history by pressing the <gui> You could link History against ephy-history.page I'd say. @@ +62,3 @@ + <section><title>Go back and forth</title> + <p>You can use the toolbar to navigate through your web history by pressing the <gui> +Back</gui> and <gui>Forward</gui> buttons on the left of the toolbar.<media type="image" mime="image/png" src="figures/ephy-back-forth.png"></media></p> This looks a bit ugly in Yelp as the image directly follows the text. Maybe have a link break and a colon after "toolbar" instead? ::: help/C/ephy-web-app.page @@ +52,3 @@ + <title>Web Application mode</title> + <p>Some Web pages might be used as if they were applications. Web allows you to install these pages. When you do open these applications, the page will display using <link type="guide" xref="windows#fullscreen">fullscreen</link> and without <gui>Toolbar</gui> to reserve all space for the Web Page itself.</p> + <p>If you do open a link pointing to another page, a page will open on a separate <app>Web</app> window.</p> Not sure if the emphasis by using "do" is intended here? ::: help/C/ephy-windows-tabs.page @@ +56,3 @@ + <p>To Switch in Between Tabs : Select the header of a tab to switch to it.</p> + <p>To rearrange tabs in the current window, you can also drag tabs to reorder them.</p> + <note style="tip"><p>You can also access these options by opening the context menu of the tab header.</p></note> But how do I open a "context menu"? :) Mentioning right-clicking here might make sense. ::: help/C/index.page @@ +49,3 @@ + + <title>Web Help</title> + <p><app>Web</app> is the GNOME Web browser, formerly known as <app>Epiphany</app>. It aims to be simple to use and standards compliant. You can read this small <link xref="introduction">introduction</link> of browse the different topics below.</p> typo: of should be or @@ +54,3 @@ + </section> + + <section id="content" style="2column"><title>Pages content</title> In general the capitalization here and in other places is inconsistent - sometimes you use "Foo Bar Foo", sometimes "Foo bar foo". I prefer using capitalization for headers everywhere, except for common words such as "a", "of", "the" etc.
Created attachment 219604 [details] [review] Mallard manual with review
Thanks for the review I did remove trailing whitespaces, typo, syntax error, added revision markup for two pages, sticked to website / webpage. I had to remove link to galeon on sourcefourge for smart bookmarks.. unfortunately I do not know any replacement. Also, I linked to gnome-desktop help for printing and used "clicked on the top bar on Web menu" for the application menu. (Patch for F1 shortcut and help menu item still needed)
Review of attachment 219604 [details] [review]: Salut, thanks for all the improvements and the quick new patch! Again a quick (and rather unstructured, thanks to the party yesterday evening that still makes parts of my brain run rather slow) review, live from the city of A Coruña. There might be more things that could be improved but I didn't find them (yet) because I haven't had a coffee yet, but at least some yummy cookies. In general, the capitalization of <desc>s is inconsistent, for example: <desc>To Change the Zoom Factor</desc> vs <desc>Enter web address, go back and forth or simply search</desc>. Maybe keep all <desc>s in normal spelling, and use capitalization only for the <title>s? You use "Setting Your Preferences" and "Using the Download Manager" (verbs are gerunds), but "Find some Text on a Website" and "Print a webpage" (verbs are infinitives). This should be consistent. ::: help/C/ephy-bookmarks-management.page @@ +6,3 @@ + <info> + <link type="guide" xref="bookmarks"/> + <license><p>GNU Free Documentation License (GFDL), Version 1.1</p></license> In general: Would be good to contact gnome-doc-list@ as I'm not sure if we still prefer GFDL or rather Creative Commons nowadays (I used CC for the user documentation that I write). Both are rather incomaptible towards each other. In case that you used existing documentation which was GFDL 1.1 licensed it would be required to either ask ALL authors to relicense to a specific CC variant and version, or (less preferable) to dual-license to GFDL 1.3 and CC. Disclaimer: I am not a lawyer. @@ +70,3 @@ + <p>To bookmark a link in the currently viewed webpage, open the link context menu and choose <gui>Bookmark Link...</gui>.</p> + </item> + <item><p>History Window: To bookmark the currently selected history link, choose <guiseq><gui>File...</gui><gui>Add Bookmark</gui></guiseq> . Alternatively, select <gui>Add Bookmark</gui> from the history link context menu.</p></item> Whitespace in front of the fullstop. But it's the only place in your patch. :) ::: help/C/ephy-common-questions.page @@ +54,3 @@ + + <section id="adobe" style="2column"><title>Adobe Flash does not work</title> + <p>The Adobe Flash plugin uses GTK+2, while Epiphany and WebKitGTK+ use GTK+3. It is not possible to link, in the same process, to different versions of GTK+, so unfortunately the flash plugin cannot work as it is. In the short term we suggest to use nspluginwrapper to load the plugin (it's been verified to work at least on Fedora Linux). In the longer term, Flash will work again out-of-the-box when we migrate to WebKit2, since it runs all plugins in a different process.</p> Do we really want to tell an average user the technical reasons (linking in the same process), especially as the term "link" in a Webbrowser context has a different conotation? @@ +55,3 @@ + <section id="adobe" style="2column"><title>Adobe Flash does not work</title> + <p>The Adobe Flash plugin uses GTK+2, while Epiphany and WebKitGTK+ use GTK+3. It is not possible to link, in the same process, to different versions of GTK+, so unfortunately the flash plugin cannot work as it is. In the short term we suggest to use nspluginwrapper to load the plugin (it's been verified to work at least on Fedora Linux). In the longer term, Flash will work again out-of-the-box when we migrate to WebKit2, since it runs all plugins in a different process.</p> + <p><link type="guide" href="http://www.gnu.org/software/gnash/Gnash">Gnash</link> is an open source flash movie player from the GNU project. <link type="guide" href="http://lightspark.github.com/">Lightspark</link> is an LGPLv3 licensed Flash player and browser plugin.</p> You could provide install links here if you want here. Feelfree to take a look at the code in http://git.gnome.org/browse/evolution/tree/help/C/exchange-connectors-overview.page which shows how to use <link action="install:packagename"> :) @@ +56,3 @@ + <p>The Adobe Flash plugin uses GTK+2, while Epiphany and WebKitGTK+ use GTK+3. It is not possible to link, in the same process, to different versions of GTK+, so unfortunately the flash plugin cannot work as it is. In the short term we suggest to use nspluginwrapper to load the plugin (it's been verified to work at least on Fedora Linux). In the longer term, Flash will work again out-of-the-box when we migrate to WebKit2, since it runs all plugins in a different process.</p> + <p><link type="guide" href="http://www.gnu.org/software/gnash/Gnash">Gnash</link> is an open source flash movie player from the GNU project. <link type="guide" href="http://lightspark.github.com/">Lightspark</link> is an LGPLv3 licensed Flash player and browser plugin.</p> + <p>Some sites might allow you to leverage HTML5 instead relying on flash, eg <link type="guide" href="http://www.youtube.com/html5">Youtube</link>.</p> It's "e.g." instead of "eg" @@ +59,3 @@ + </section> + + <section id="bookmarks"><title>How works bookmarks system?</title> "How does the Bookmarks system work?" @@ +60,3 @@ + + <section id="bookmarks"><title>How works bookmarks system?</title> + <p>The traditional way of organizing bookmarks is too unnatural, so Epiphany organizes bookmarks by topic, which causes differences with traditional bookmarks systems: "Epiphany" instead of "Web" @@ +63,3 @@ + +Bookmarks can be associated with multiple topics. +The recommended way to access bookmarks is the bookmarks window, not the bookmarks menu. If you remember the title of the bookmark you're looking for, type the first few characters of it in the location bar, and matching bookmarks will be shown in a drop down menu.</p> Here you write "drop down", sometimes you write "drop-down". http://developer.gnome.org/gdp-style-guide/stable/gnome-glossary-desktop.html.en uses "drop-down". ::: help/C/ephy-privacy-clean.page @@ +50,3 @@ + + <title>Clearing your personal data</title> + <p><app>Web</app> lets you clear all your personal data it remembered. Click on the tob bar on <guiseq><gui>Web</gui><gui>Personal Data</gui></guiseq> to open the <gui>Personal Data Manager</gui>.</p> Typo: top ::: help/C/ephy-setup-downloads.page @@ +51,3 @@ + + <title>Choose downloads folder</title> + <p>Choose the folder for downloaded files by pressing the <gui> Download folder</gui> button and selecting a folder. If you select <gui>Automatically download and open files</gui> you will not be prompted before files are download or opened.</p> There are a few tabs here that shouldn't be here. ::: help/C/ephy-setup-privacy.page @@ +55,3 @@ + <list> + <item><p>Select <gui>Allow popup windows</gui> if you want webpages to be able to launch content in new windows automatically.</p></item> + <item><p>Select <gui>Enable Java</gui> to allow pages to load Java applets - programs which run inside webpages.</p></item> It was not clear to me what the dash was meant to mean. Maybe replace it by "These are..."? @@ +56,3 @@ + <item><p>Select <gui>Allow popup windows</gui> if you want webpages to be able to launch content in new windows automatically.</p></item> + <item><p>Select <gui>Enable Java</gui> to allow pages to load Java applets - programs which run inside webpages.</p></item> + <item><p>Select <gui>Enable JavaScript</gui> to give webpages the capability to use the more advanced programming techniques of the JavaScript language.Disabling these features may cause some pages to display incorrectly or cause some loss of functionility. For Java to work, you need to install the Java plugin.</p></item> nguage.Disabl misses a whitespace. Why is "for Java to work" listed under the "JavaScript" item instead of the Java item? Also, would it be possible to provide a link or explain how to actually install that? ::: help/C/ephy-setup-search-engine.page @@ +16,3 @@ + + <title>Define the Default Search Engine</title> + <p>To change the default search engine for <app>Web</app>, enter a terminal and input following code: <cmd>gsettings set org.gnome.Epiphany keyword-search-url</cmd> followed by the webaddress you want to use as default, then <cmd>%s</cmd>.</p> I'd make this "open the terminal application and enter the following command:" (you could say "put in" but it feels a bit out of place to me. Plus the user won't enter "code", whatever that scary term means, but simply a command.) @@ +17,3 @@ + <title>Define the Default Search Engine</title> + <p>To change the default search engine for <app>Web</app>, enter a terminal and input following code: <cmd>gsettings set org.gnome.Epiphany keyword-search-url</cmd> followed by the webaddress you want to use as default, then <cmd>%s</cmd>.</p> + <p>Eg, to use <app>Duck Duck Go</app> as a default engine, enter a terminal and run <cmd>gsettings set org.gnome.Epiphany keyword-search-url http://duckduckgo.com/?q=%s</cmd>.</p> Several things: I wouldn't start a sentence with "Eg" (which probably was meant as "e.g.") but rather "For example,". In general I'd write "web address" as two words. And one problem with these instructions is: I enter that command and add the web address of my favorite engine: http://duckduckgo.com. Then I add %s to it, and the result is http://duckduckgo.com%s . Probably not what you wanted. :) bookmarks-smart-bookmarks.page describes this in a way better way - maybe refer to it or reuse it (without duplicating content). :) ::: help/C/ephy-setup-style.page @@ +51,3 @@ + + <title>Define your own style</title> + <p>This section allows you to configure the style of text and the colors used on webpages.</p> The section itself doesn't really allow me this - the application maybe does, but not this help file. :) @@ +54,3 @@ + <list> + <item> + <p>You can set a minimum size for webpage fonts by using the <gui> Minimum size</gui> spin box. Fonts smaller than this value will be increased to this size.</p> Whitespace that should not be there: <gui> Minimum size</gui> @@ +65,3 @@ + </item> + <item> + <p>You can make <app>Web</app> use a smooth scrolling effect by selecting the <gui>Use smooth scrolling</gui> option.</p> This section makes me feel a little bit uncomfortable because it uses the same words for both the option name and for describing the option. It's a bit like "Click Save to save" or "Eat food in order to eat food" but I cannot come up with something better either now. ::: help/C/ephy-setup.page @@ +51,3 @@ + + <title>Setting Your Preferences</title> + <p>You can customize <app>Web</app> to suit your personal needs by using the <gui>Preferences</gui> dialog which can be accessed by clicking on <gui>Web</gui> on the tob bar then selecting <gui>Preferences</gui></p> I'm not sure if I consider this page helpful. "Preferences" is rather vague / generic and covers lots of stuff, and I would search for how to do a *specific* task instead, plus the menu position of "Preferences" is rather consistent among GNOME applications so it should be easier to find it. ::: help/C/ephy-shortcuts.page @@ +7,3 @@ + <link type="guide" xref="index"/> + <license><p>GNU Free Documentation License (GFDL), Version 1.1</p></license> + <desc>The full Web Cheat Sheet</desc> While I know what a "Cheat Sheet" is, I'm pretty sure that for a good amount of average users this is not helpful... :) @@ +64,3 @@ + <tbody> + <tr> + <td><p>Open a file from a local folder.</p></td> <td><p><key>Ctrl</key> + <key>O</key></p></td> In general everywhere on this page: Please use <keyseq><key>Ctrl</key><key>O</key></keyseq> markup for this. Bonus: You can then drop the confusing plus signs which readers might consider to be a key to press on the keyboard. ::: help/C/ephy-toolbar.page @@ +53,3 @@ + <p>The toolbar allows you to navigate from one site to another.</p> + + <section id="location-bar"><title>Search a Site or Enter Address</title> Not clear to me from the title if it's about searching on a page (for text) that you have already opened, or searching for a website (URL) by using a search engine. "web address" might also make it clearer. You say "a site" but "address" - better to use articles in both cases.
Created attachment 219865 [details] [review] Mallard manual with attempt for action install
Great, I did use your remarks to provide new one (consistent capitalization, typo, removal of "setup" page, and removed "smooth scrolling" because appart from dconf it does not exist anymore) However * the patch includes some syntax for action="install" , and the pages are read, but I cannot manage to use it (I only have message "Unmatched block element: choose" ) even with "jbhduild run yelp" . I also tryed with the example page from evolution manual * i kept the licence until answer. As you guessed, even if Creative Commons is to be choosed, I'll have to contact authors from previous version...
Hi everyone! Pierre-Yves, the licence switch is one of the main reasons for rewriting help in Mallard, but this is usually not a problem because the style changes enough that it is no more time consuming to write the help from scratch, which is what we usually do. How much effort have you put into porting the help to Mallard? Have you just split the DocBook help into multiple files, or have you been rewriting the style as well? If you have not spent much time on it, it would make sense to start again and work in a branch on git so that all the authors are credited properly, so that it is easy to contribute to and because great big patches are not nice to review on bugzilla. If you are ok with going ahead like this, then I will close this bug as obsolete and open a new one for the re-write as this has turned out bigger than the original bug :) Looking forward to your reply!
"How much effort have you put into porting the help to Mallard? Have you just split the DocBook help into multiple files, or have you been rewriting the style as well?" Starting from scratch might make sense the work was more than just a split (some features were obsolete, some parts added). Nonetheless I kept as it were some sentences and only received agreements from 5 of the previous author (I can email you the detail but it means tracking old contributors...)
Is there any way I can contribute to this?
Structure pushed to master in commit dbb87b0a5b3c450aaa3b4cafc56f06ee44d18e92. Please make sure to stick to the style so that pages remain tidy and maintainable. If anyone does not feel confident enough to work on master, we can work on a branch or you can attach patches here. Don't forget to validate before committing and have fun! :)
The new help is coming along quite well and should be ready for the release on Monday. It would be great if the maintainers could hold off on the release until the build system is set up for the help and the buttons link to it properly.
Closing this as the new docs are already in master. It only remains getting the patches in the build-related bug committed.