The ultimate assistant was: Re: page-position="last" - bug?

["J.Pietschmann" <j3...@yahoo.de>]

Clay Leeds wrote:
> ON a side-note, it'd be bitchin if we had some sort of nifty "FOP Answer
> Wizard" on the site, where one could posit: Has feature X been
> implemented?" and it would search the compliance.xml document for a
> "yes" in the supported column.

If you know the exact name of the element/property, getting the
page in a browser and hitting ctrl-f is your wizard.
Implementing a wizard where you don't need to know the exact name
is reaching for the holy grail of AI research. Apart from this,
people will ask for all kind of (mis)features of related techs,
like why FOP doesn't accept  , -- in comments, SVG gradients,
xsl:script, SAX1 and where the memory is gone.

The majority of newbies starts with a problem and seeks a solution.
Parts of the FAQ, in particular section 8, are problem and task
oriented for exactly this reason. I think it would be a good idea
to have a "solutions" page where the code and detailed explanations
from sections 4 (servlet), 6.3-6.6 and 8 can be factored out so that
the FAQ can be made shorter by pointing to the more voluminous
articles there. This would allow more alias descriptions for common
problems.

The slightly more advanced semi-noobs who think they can solve the problem
on their own but can't quite get it working are harder to deal with. There
is nothing worse than something which looks like an "almost there"
solution, because it's almost always a dead end (no offense, but the recent
question about manipulating the area tree for rendering a SVG into PDF is
an excellent example). The worst obstacle is the chicken effect: like
chicken accepting an old boot as their mother if it is properly introduced,
most people stick to the patters they used to get their equivalent of
"Hello World" working. In this cases the wrong approach to the problem is
the problem, but because there are so much wrong approaches it is difficult
to provide effective help: first the original problem has to be
reestablished. Occasionally the chicken effect causes enough users to
follow the same wrong path, but in the XSLT/FO area self-taught users seem
still to be the majority.

J.Pietschmann


---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org

RE: The ultimate assistant was: Re: page-position="last" - bug?

[Victor Mote <vi...@outfitr.com>]

Victor Mote wrote:

> BTW, I am going to beef up the graphic image doc (see my recent reply to
> your message on fop-user re: the same). It will involve a link on the left
> menu that will say "Graphic Formats" or something similar. If the
> user can't
> translate "TIFF" to "Graphic Formats", then I doubt there is
> anything I can
> do for them anyway.

This is all done now, and I have published it (I think it will be "live" in
another couple of hours). A couple of potential problems:
 1) I simply added the newly documented graphic formats to the svg.xml file.
Perhaps it should be renamed (i.e. deleted and added with a new name) to
graphics.xml.
 2) I also did some more rearranging of the menu items, so that everything
that was in "Extras" is now under "Features".

I am pretty happy now with the structure and content of the user section of
the web site. There is some polishing to be done, but I can't think of any
major holes or confusing items. Obviously, on-topic user questions that
can't be answered with a self-evident link are evidence to the contrary, so
please keep updating the content.

I would probably try to merge the user & dev "examples", but since we are
using 1.0dev to build the pdfs, I am guessing that maybe we don't want all
of the examples showing up right now anyway. Does that sound right??

BTW, some of the changes I have made, esp. to the left menu are probably
matters of taste rather than principle. I hope I haven't offended anyone
else's taste in the process. I am hopeful that those changes will help the
user find the needed content more easily. I finally decided that it is
probably easier to ask forgiveness rather than permission on this stuff.
Please change any of it if you wish.

I'll probably turn my attention to the dev pages now. If that goes well, I'd
like to go fishing for some more developers.

Victor Mote


---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org

RE: The ultimate assistant was: Re: page-position="last" - bug?

[Victor Mote <vi...@outfitr.com>]

Clay Leeds wrote:

> This change looks good. One potential problem is if folks search the FAQ
> page (cmd/ctrl-f) for "threads", and receive "No text matched your
> search" or something.

"thread + fop" in the search box gives some useful results (right now it is
pointing to the old content).

> Some "dummy" text in parentheses could be included (not unlike META
> Keywords) in the FAQ response above the off-page link. I was going to
> give an example, but the only thing I can think of is "My PNG images
> don't work" the answer to which (download Sun's JIMI or JAI) is also
> useful for implementing other image types like PSD, TIFF and MacPaint.
> Hence, including "(JIMI also works for PSD, TIFF, Targa, etc...)" or
> something. I can see how one might get carried away with this, but my
> hope is not so much to keep the FAQ short and concise, but rather to
> lessen the number of questions asked to fop-user (or, god forbid
> fop-dev!) about whether or not FOP can handle TIF (or some other
> question no longer answered in the FAQ, but moved somewhere else).

This may boil down to a different philosophy of FAQ. I don't want to try to
include all content, or even links to all content in the FAQs. In fact, the
main thing I am trying to accomplish right now is to get all duplicate doc
removed, and use cross-refs instead. The site-wide search should cover the
case that you mention. I agree that the goal is to minimize fop-user
traffic, i.e. to help the user find it on the website first. IMO, the best
way to do this is to 1) beef up the content pages, and 2) make sure that the
content is in a place that is intuitive for the user to find. Then the FAQs
become a mere crutch. To a certain extent, our FAQs should read (as many of
them now do) Q: "How do I XYZ?" A: "See <link>doc for XYZ</link>."

BTW, I am going to beef up the graphic image doc (see my recent reply to
your message on fop-user re: the same). It will involve a link on the left
menu that will say "Graphic Formats" or something similar. If the user can't
translate "TIFF" to "Graphic Formats", then I doubt there is anything I can
do for them anyway.

Victor Mote


---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org

Re: The ultimate assistant was: Re: page-position="last" - bug?

[Clay Leeds <cl...@medata.com>]

Victor,

Victor Mote wrote:
> OK, I have completed this work. Rather than moving the content to a general
> "solutions" page, I have moved it to a specific document where such content
> belongs. The servlet content got moved to embedding.xml, the pdf-specific
> content to output.xml, and I created a new file, fo.xml as a resource for
> xml & xsl-fo content. The FAQ still contains the old questions, but the
> answers are now links to the content. My hope is that users now have two
> ways to find the content: through the menus and through the FAQs.

This change looks good. One potential problem is if folks search the FAQ
page (cmd/ctrl-f) for "threads", and receive "No text matched your
search" or something.

Some "dummy" text in parentheses could be included (not unlike META
Keywords) in the FAQ response above the off-page link. I was going to
give an example, but the only thing I can think of is "My PNG images
don't work" the answer to which (download Sun's JIMI or JAI) is also
useful for implementing other image types like PSD, TIFF and MacPaint.
Hence, including "(JIMI also works for PSD, TIFF, Targa, etc...)" or
something. I can see how one might get carried away with this, but my
hope is not so much to keep the FAQ short and concise, but rather to
lessen the number of questions asked to fop-user (or, god forbid
fop-dev!) about whether or not FOP can handle TIF (or some other
question no longer answered in the FAQ, but moved somewhere else).

This brings to mind searching the phone book for the "Cinema" entry,
only to be re-directed to "Movie Theater"... At least with the web, it's
just a click...

-- 
Clay Leeds - cleeds@medata.com
Web Developer - Medata, Inc. - http://www.medata.com
PGP Public Key: https://mail.medata.com/pgp/cleeds.asc


---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org

RE: The ultimate assistant was: Re: page-position="last" - bug?

[Victor Mote <vi...@outfitr.com>]

Victor Mote wrote:

> J.Pietschmann wrote:
>
> > The majority of newbies starts with a problem and seeks a solution.
> > Parts of the FAQ, in particular section 8, are problem and task
> > oriented for exactly this reason. I think it would be a good idea
> > to have a "solutions" page where the code and detailed explanations
> > from sections 4 (servlet), 6.3-6.6 and 8 can be factored out so that
> > the FAQ can be made shorter by pointing to the more voluminous
> > articles there. This would allow more alias descriptions for common
> > problems.
>
> I agree -- it is on its way.

OK, I have completed this work. Rather than moving the content to a general
"solutions" page, I have moved it to a specific document where such content
belongs. The servlet content got moved to embedding.xml, the pdf-specific
content to output.xml, and I created a new file, fo.xml as a resource for
xml & xsl-fo content. The FAQ still contains the old questions, but the
answers are now links to the content. My hope is that users now have two
ways to find the content: through the menus and through the FAQs.

As always, please let me know if this does not meet with your approval.

I have "refresh"ed the web site, so the new scheme can be viewed from the
link at forrestbot.cocoondev.org. I have some unrelated content changes to
make later today, after which I will publish.

Two caveats:
 1) the embedding page may need some reorganization. I am pretty weak with
this content, but it seems to me that the "servlet" topic is a subset of the
bigger "embedding" topic. So some content is specific to servlets, other is
more general to embedding, including servlets. I suspect that embedding.xml
needs to be rearranged a bit to make this more clear.
 2) I changed a bunch of the ids on the faq page, mostly to change
underscore characters (_) to hyphens (-) so that the related URLs are more
readable in emails. I apologize for the inconvenience. I don't intend to
make a habit of it, but I thought this warranted the change.

Victor Mote


---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org

RE: The ultimate assistant was: Re: page-position="last" - bug?

[Victor Mote <vi...@outfitr.com>]

J.Pietschmann wrote:

> The majority of newbies starts with a problem and seeks a solution.
> Parts of the FAQ, in particular section 8, are problem and task
> oriented for exactly this reason. I think it would be a good idea
> to have a "solutions" page where the code and detailed explanations
> from sections 4 (servlet), 6.3-6.6 and 8 can be factored out so that
> the FAQ can be made shorter by pointing to the more voluminous
> articles there. This would allow more alias descriptions for common
> problems.

I agree -- it is on its way.

Victor Mote

---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org