Re: More about Makebook feature in Amaya

Hi everyone,


> Having now read the documentation my thoughts are (and I offer these
> generously, not as a criticism):

Thanks for the constructive criticism! ;-)


> 1. There is no entry in the Help outline for Makebook. I had to intuit that
> "Assembling large document collections" was the help for Makebook.

+1 on this, maybe something like "Make Book" in parenthesis next to
the title would help; an expanded TOC could help as well.

In a more general approach, a feature to search in a set of linked
documents (for "search in Help" but not only) would be a neat thing to
see in a future release. A parameter would define the crawl depth of
the spider algorithm, to avoid it to be infinite (while searching in a
typical Web page with external links). :-)


> 2. Having found it I could not understand it. (Part of that may be explained
> by noting that I never work in the main view that renders the page, only in
> the HTML source. So, with the window split, "Tools" is grayed out, thus
> access to "Makebook" is blocked.)

Good point, I also already stumbled in this sort of issue (for other
options, if I recall correctly). Although it makes sense graying out
currently unavailable options (much better than hiding them IMO),
currently it doesn't occur to me a better suggestion on how to
possibly improve this...


> 3. When I switched to main view and clicked on Tools > Makebook, nothing
> happens. I now appreciate that I failed to add the markup required for
> Makebook to work; however, it seems to me that there ought to be at least a
> dialogue box that alerts the user to the failure, and what to do about it,
> or a link to the help file.

Didn't attempt to reproduce but the behavior sounds buggy IMO also...


> 4. Some examples in the help documentation would be very helpful. Since I
> never use the tools and features available in the main view, I have no idea
> how to use the Attributes tool. Can Help also include help for people who
> code directly?

I've just found (by coincidence) in one of the files shipped with Amaya:
"This document is organized as a book and you can use the Tools/Make
Book command to build and print the whole manual." [2]
Probably a good example to start with... :-)


> 5. Language such as "To refer to a document subset, you usually define a div
> element..." is confusing. If there are other ways of doing so, what are
> they?

OK, I also needed to read it a few times before clearly understanding
it. What seems to be here is just an example, in order to introduce
the feature. There are other ways of achieving it, for example one I
use more often (note that there are no "div" elements):

<h1>Section</h1>
<p>In <a href="subsect">subsection</a>, one can read "blah" several times.</p>
<h2 id="subsect">Subsection</h2>
<p>Blah blah blah</p>

Suggestion: "To refer to a document subset, you usually define a div
element to identify the part of the document you want to include, and
you create a link to this div element." --> "To refer to a document
subset, one should define a container element (such as a
<code>div</code>) holding the part of the document to be included, add
an identifier to it and create a link to this element." Changing
"holding" to "enclosing" may help making it slightly more clear. :-)


Couple of nits:
 I. In the "Assembling large document collections" page shipped with
Amaya 11.3.1:
   "Amaya changes these values ss needed, [...]" --> "Amaya changes
these values as needed, [...]" (typo)
 II. The online version [1] of the Manual seems outdated, i.e., it
doesn't (at least visually) match any of the files shipped with Amaya
[2] [3]:
   The difference seems to reside (at least) in "styles.css".


> Regards,
> Bill B

Cheers,
 Helder


[1] http://www.w3.org/Amaya/User/doc/Manual.html
[2] In Windows, "%ProgramFiles%\Amaya\doc\WX\Index.html"
[3] In Windows, "%ProgramFiles%\Amaya\doc\WX\Manual.html"

Received on Wednesday, 24 February 2010 08:01:50 UTC