Randy McMurchy wrote:
I have some thoughts about the whole idea of problematic UTF-8
packages, and I'd like your feedback on the ideas.
1) I was wrong about this requiring just a note, however, I
do feel a Warning is too strong also. I believe the perfect
compromise is using the <caution> tags. Nice yellow icon with
the exclamation point will catch the readers attention, yet
won't scare them off.
Good idea. You obviously know DocBook better than me :)
2) I now feel, because of the possibility of long technical
explanations, that it may be best to create a *separate* page
in the book, probably in Chapter 2 "Important Information", where
all the information about UTF-8 issues will be presented. All
the packages with issues will be presented here, each with its
own section identified with an <id> tag.
a) The <caution> tag will still be on the respective page
(UnZip, for example) and in this caution box will be a note
with text similar to this:
"This package is known to have issues if used in UTF-8 locales.
For complete information, see <xref linkend=>."
b) The xref link will be to the UTF-8 issues page to the spot
on the page for that exact text (using the "id" tags).
OK
c) I'm suggesting this as I believe the text about the UTF-8
issues (if UnZip will be a representative example) is very
long, will take up much space on the page, so much so that I
think it will distract from the real material.
I think that UnZip is not a representative example of the whole picture.
Probably the issues are best classified into the following groups:
1) Issues that have an easy solution such as a patch (e.g., cdrtools) or
version upgrade (nano-1.2.5 => 1.3.9) probably won't have a long text
about possible solutions.
2) Issues that are best illustrated with a screenshot (e.g., MC if there
were no Ubuntu patch) probably don't need many words. Even if we don't
insert a screenshot, a person will try the packege despite our "caution"
sign, see that it is indeed obviously broken, and give up. For
English-only speaking editors, an XML comment (i.e. thing invisible to
the regular readers) that describes details is probably sufficient in
such cases.
3) Issues that are important, non-obvious to English readers and have no
easy solution (like UnZip issue) do tend to take up space.
But let's indeed add some material and see how it looks like in the book.
BTW the UnZip issue is not a UTF8-only issue, it affetcs all
non-ISO-8859-1 locales, some of them are traditional 8-bit locales. So
you may want to rename the page from "UTF-8 issues" to "locale related
issues".
d) For readers that don't care about UTF-8 issues, they can
simply skip right by the Caution and continue. For readers who
might be affected by the issues, certainly they'll follow the
link and read the relevant material.
Agreed
e) Having all the UTF-8 issues centralized is good because if
readers stumble upon this page, or takes one of the links to
it, she'll then at that point be able to see all of the packages
that have UTF-8 issues.
Indeed, this will help her planning the further build.
What do you think of this idea?
+1, I think that tomorrow I will post common text for MP3 players (it
will be probably as long as for UnZip). Please suggest some place for it.
I want your version of MC breakage description,
Alex, there's probably nobody more qualified to write and describe
these issues.
The point was that it is best illustrated with a screenshot, not by
means of words.
--
Alexander E. Patrakov
--
http://linuxfromscratch.org/mailman/listinfo/blfs-dev
FAQ: http://www.linuxfromscratch.org/blfs/faq.html
Unsubscribe: See the above information page
