Re: links in the OpenBSD FAQs
An important note: I missed one of the advices of Tom Cosgrove... I would replace the OpenBSD's Flavors link in the patch with something like section 5 (as Tom suggests) or either FAQ 5, flavors as found on other parts of the FAQ. Tom suggestion is more readable, though. Of course, there are other alternatives as section 5, flavors,. By the way, these FAQ X, word entries are sometimes typed FAQ X - word, don't know if it is what maintainer are looking for, or just a minor mistake. I suppose that using a hyphen can make these entries in the FAQ look nice on a browser or PDF reader (links have different colors than standard text) but more difficult to read on text. On the other hand, I supose that sometimes using lowercases (e.g., replacing Upgrade Guide with upgrade guide) is advisable. Lowercase letters will probably follow better the BSD style. At last, I want to say again that this patch is only a draft. I am awaiting for all the changes recommended by the maintainers and certainly do not expect the final patch to be as this one. I am not proposing this patch, but only providing a draft to work on it. Cheers, Igor.
Re: links in the OpenBSD FAQs
D'oh! Of course, the SIMH entry in the FAQ 12 should read Instructions can be found _at the_ OpenBSD/vax on SIMH page. Well... there are people with more appropriate english skills that will probably suggest a lot of changes like this one. Igor.
Re: links in the OpenBSD FAQs
I cannot see why making a patch to change the links is difficult. I will look at the cvs repository as soon as I get some time and submit a patch. In any case, I would appreciate a carefully review of it, just to fit it to the taste of the developers. Igor.
Re: links in the OpenBSD FAQs
Igor Sobrado wrote: I cannot see why making a patch to change the links is difficult. I will look at the cvs repository as soon as I get some time and submit a patch. In any case, I would appreciate a carefully review of it, just to fit it to the taste of the developers. Igor. It's harder than it looks (at least for me). Keep in mind, the PRIMARY usage by most readers is via web browser, so making it an awkward read to the majority so the text and PDF readers are happier is not really what I'm after. The result should be comfortably readable, not yelling at the reader, THE AUTHOR WAS WORKING HARD TO AVOID SAYING 'click _here_' AND WROTE THIS LONG, AWKWARD SENTENCE. What I'd put in an e-mail is different than how I'd present the same idea on a web page, on a flat text file, in a book, verbally delivered in person by me, or verbally delivered in person by someone else. Each format has its strengths. I'd like to maintain the strengths of the Web format. If improving it for .TXT or .PDF can be done, great, but if it hurts the web format, I'll not be happy. One option might be a see also section at the end of appropriate articles, listing the significant cross-references. I've tried that in a few places...not sure I like it yet. Nick.
Re: links in the OpenBSD FAQs
Attached is the first draft of the patch. Once it has been debugged I will open a bug report on it. Please, check carefully all the entries in the patch and do not trust on my English skills. Some suggestions: - replacing references to threads in the mailing lists (now the thread subject) for its exact reference. There is a risk for two threads having the same subject. - there are some manual pages references (in the form command(section)) that are no links. Should these references to man pages be links? diff -urNp www/faq1.html www.new/faq1.html --- www/faq1.html 2006-12-07 17:05:55.0 +0100 +++ www.new/faq1.html 2006-12-07 18:55:51.0 +0100 @@ -275,7 +275,8 @@ Theo de Raadt, located in Canada. The OpenBSD team makes a new release every six months, with target release dates in May and November. More information on the development cycle -can be found a href=faq5.html#Flavorshere/a. +can be found in the a href=faq5.html#FlavorsOpenBSD's Flavors/a +subsection of this FAQ. a name=Included/a h21.8 - What is included with OpenBSD?/h2 @@ -362,7 +363,7 @@ Of course, additional applications can b !-- XXXrelease -- The complete list of changes made to OpenBSD 3.9 to create OpenBSD 4.0 -can be found a href=../plus40.htmlhere/a, however here are a few +can be found in the a href=../plus40.htmlOpenBSD 4.0 changes/a list, however here are a few changes the OpenBSD team anticipate will require or warrant some special note to people upgrading or installing OpenBSD 4.0 who are familiar with older versions: diff -urNp www/faq12.html www.new/faq12.html --- www/faq12.html 2006-12-07 17:05:55.0 +0100 +++ www.new/faq12.html 2006-12-07 19:02:48.0 +0100 @@ -546,7 +546,7 @@ Yes! lt;pgt; The lt;a href=quot;A HREF=http://simh.trailing-edge.com/;http://simh.trailing-edge.com//Aquot;gt;SIMHlt;/agt; VAX simulator can be used to effectively emulate a real VAX. -Instructions can be found lt;a href=quot;../vax-simh.htmlquot;gt;herelt;/agt;. +Instructions can be found in the lt;a href=quot;../vax-simh.htmlquot;gt;OpenBSD/vax on the SIMHlt;/agt; VAX simulator URL. lt;pgt; @@ -564,4 +564,4 @@ Instructions can be found lt;a href=qu lt;smallgt;$OpenBSD: faq12.html,v 1.79 2006/11/01 03:07:32 nick Exp $lt;/smallgt; lt;/bodygt; lt;/htmlgt; -/PRE \ No newline at end of file +/PRE diff -urNp www/faq13.html www.new/faq13.html --- www/faq13.html 2006-12-07 17:05:55.0 +0100 +++ www.new/faq13.html 2006-12-07 20:10:58.0 +0100 @@ -915,8 +915,8 @@ with normal DVD players. lt;pgt; The important thing is you use media which suit your DVD writer. If you expect compatibility with other DVD players, watch your step and -be sure to read -lt;a href=quot;A HREF=http://www.dvddemystified.com/dvdfaq.html;http://www.dvddemystified.com/dvdfaq.html/A#4.3.1quot;gt;this sectionlt;/agt; +be sure to read the +lt;a href=quot;A HREF=http://www.dvddemystified.com/dvdfaq.html;http://www.dvddemystified.com/dvdfaq.html/A#4.3.1quot;gt;compatibility problems sectionlt;/agt; of the DVD FAQ. lt;h4gt;DVD writing speedlt;/h4gt; @@ -1294,9 +1294,9 @@ codecs). Some Real Audio streams can be made to work on i386 using lt;bgt;mplayerlt;/bgt; in conjunction with the lt;ttgt;graphics/win32-codecslt;/ttgt; and lt;ttgt;emulators/redhat/baselt;/ttgt; ports -(see -lt;a href=quot;A HREF=http://marc.theaimsgroup.com/?t=10706051031;http://marc.theaimsgroup.com/?t=10706051031/Aamp;amp;r=1amp;amp;w=2quot;gt;this -threadlt;/agt; on the ports mailing list). +(see the thread +lt;a href=quot;A HREF=http://marc.theaimsgroup.com/?t=10706051031;http://marc.theaimsgroup.com/?t=10706051031/Aamp;amp;r=1amp;amp;w=2quot;gt;Confusion +with Mplayer (resend with data)lt;/agt; thread on the ports mailing list). lt;a name=quot;javaflashquot;gt;lt;/agt; lt;a name=quot;javapluginquot;gt;lt;/agt; @@ -1413,4 +1413,4 @@ this would be interesting, but lack of h lt;/bodygt; lt;/htmlgt; -/PRE \ No newline at end of file +/PRE diff -urNp www/faq14.html www.new/faq14.html --- www/faq14.html 2006-12-07 17:05:55.0 +0100 +++ www.new/faq14.html 2006-12-07 20:14:41.0 +0100 @@ -140,9 +140,8 @@ post-install, as well. lt;pgt; There is not one quot;rightquot; way to label a disk, but there are many wrong ways. -Before attempting to label your disk, see -lt;a href=quot;faq4.html#Partitioningquot;gt;this discussionlt;/agt; on partitioning and -partition sizing. +Before attempting to label your disk, see the FAQ +lt;a href=quot;faq4.html#Partitioningquot;gt;section on partitioning and partition sizinglt;/agt;. lt;pgt; For an example of using disklabel(8) during install, see the @@ -1684,8 +1683,8 @@ man pagelt;/agt; lt;pgt; Many OpenBSD lt;a href=quot;../plat.htmlquot;gt;platformslt;/agt; include support for various hardware RAID products. nbsp;The options vary by platform, see the -appropriate hardware support page (listed -lt;a
Re: links in the OpenBSD FAQs
Hi Nick. I read your post after sending the patch. I will do my best to make these links as short as possible. Don't know your taste on this matter, but I do not dislike relatively long links if these links make the text more readable, and it is independent of the format of the document being used. By now, I have submitted the patch and I will be listening for any suggestion. My goal is writing the best possible patch to make the developer that will manage the bug report (and, of course, the maintainers of the FAQ) happy. I will continue checking the changes for other issues too. Cheers, Igor.
Re: links in the OpenBSD FAQs
Igor Sobrado 7-Dec-06 19:29 Attached is the first draft of the patch. Once it has been debugged I will open a bug report on it. Please, check carefully all the entries Don't create a bug report for this. This is not a bug. This is a change of style that you (and some others) would like to see in the FAQ. Nick, myself, and other people who work on the FAQ read misc@; there's no point just pi**ing us off by calling this a bug. diff -urNp www/faq1.html www.new/faq1.html --- www/faq1.html 2006-12-07 17:05:55.0 +0100 +++ www.new/faq1.html 2006-12-07 18:55:51.0 +0100 @@ -275,7 +275,8 @@ Theo de Raadt, located in Canada. The OpenBSD team makes a new release every six months, with target release dates in May and November. More information on the development cycle -can be found a href=faq5.html#Flavorshere/a. +can be found in the a href=faq5.html#FlavorsOpenBSD's Flavors/a +subsection of this FAQ. I personally find this clunky. It now reads: More information... can be found in the OpenBSD's Flavors subsection of this FAQ. I personally prefers something along the lines of More information... can be found in section 5 of the FAQ. (with the link on section 5 of the FAQ) But Nick and I discuss changes like this backwards and forwards quite a bit from time to time... that is why this is not a mechanical set of changes, but one that requires a lot of effort and no small ability with the English language a name=Included/a h21.8 - What is included with OpenBSD?/h2 @@ -362,7 +363,7 @@ Of course, additional applications can b !-- XXXrelease -- The complete list of changes made to OpenBSD 3.9 to create OpenBSD 4.0 -can be found a href=../plus40.htmlhere/a, however here are a few +can be found in the a href=../plus40.htmlOpenBSD 4.0 changes/a list, however here are a few Here I personally prefer ... can be found in plus40.html. (with the link in the obvious place) (i.e. sometimes the general form can be found at a href=xx/a. works well. Especially since someone without an active link should be able to find the target without undue searching - at least, if this exercise is to be worthwhile). Keep on with this, though Many thanks Tom
Re: links in the OpenBSD FAQs
Igor Sobrado [2006-12-07, 20:29:23]: Attached is the first draft of the patch. Once it has been debugged I will open a bug report on it. Please, check carefully all the entries in the patch and do not trust on my English skills. Some suggestions: - replacing references to threads in the mailing lists (now the thread subject) for its exact reference. There is a risk for two threads having the same subject. - there are some manual pages references (in the form command(section)) that are no links. Should these references to man pages be links? diff -urNp www/faq1.html www.new/faq1.html --- www/faq1.html 2006-12-07 17:05:55.0 +0100 +++ www.new/faq1.html 2006-12-07 18:55:51.0 +0100 @@ -275,7 +275,8 @@ Theo de Raadt, located in Canada. The OpenBSD team makes a new release every six months, with target release dates in May and November. More information on the development cycle -can be found a href=faq5.html#Flavorshere/a. +can be found in the a href=faq5.html#FlavorsOpenBSD's Flavors/a +subsection of this FAQ. a name=Included/a h21.8 - What is included with OpenBSD?/h2 @@ -362,7 +363,7 @@ Of course, additional applications can b !-- XXXrelease -- The complete list of changes made to OpenBSD 3.9 to create OpenBSD 4.0 -can be found a href=../plus40.htmlhere/a, however here are a few +can be found in the a href=../plus40.htmlOpenBSD 4.0 changes/a list, however here are a few changes the OpenBSD team anticipate will require or warrant some special note to people upgrading or installing OpenBSD 4.0 who are familiar with older versions: diff -urNp www/faq12.html www.new/faq12.html --- www/faq12.html2006-12-07 17:05:55.0 +0100 +++ www.new/faq12.html2006-12-07 19:02:48.0 +0100 @@ -546,7 +546,7 @@ Yes! lt;pgt; The lt;a href=quot;A HREF=http://simh.trailing-edge.com/;http://simh.trailing-edge.com//Aquot;gt;SIMHlt;/agt; VAX simulator can be used to effectively emulate a real VAX. -Instructions can be found lt;a href=quot;../vax-simh.htmlquot;gt;herelt;/agt;. +Instructions can be found in the lt;a href=quot;../vax-simh.htmlquot;gt;OpenBSD/vax on the SIMHlt;/agt; VAX simulator URL. lt;pgt; @@ -564,4 +564,4 @@ Instructions can be found lt;a href=qu lt;smallgt;$OpenBSD: faq12.html,v 1.79 2006/11/01 03:07:32 nick Exp $lt;/smallgt; lt;/bodygt; lt;/htmlgt; -/PRE \ No newline at end of file +/PRE diff -urNp www/faq13.html www.new/faq13.html --- www/faq13.html2006-12-07 17:05:55.0 +0100 +++ www.new/faq13.html2006-12-07 20:10:58.0 +0100 @@ -915,8 +915,8 @@ with normal DVD players. lt;pgt; The important thing is you use media which suit your DVD writer. If you expect compatibility with other DVD players, watch your step and -be sure to read -lt;a href=quot;A HREF=http://www.dvddemystified.com/dvdfaq.html;http://www.dvddemystified.com/dvdfaq.html/A#4.3.1quot;gt;this sectionlt;/agt; +be sure to read the +lt;a href=quot;A HREF=http://www.dvddemystified.com/dvdfaq.html;http://www.dvddemystified.com/dvdfaq.html/A#4.3.1quot;gt;compatibility problems sectionlt;/agt; of the DVD FAQ. seriously, i don't know how you are doing this, but it sure does not look like a diff against our cvs. furthermore, saad@ already started replacing here links and such a while back, but even though it was reviewed by a few people, somehow it never got into the tree. -- steven Disclaimer: http://www.kuleuven.be/cwis/email_disclaimer.htm
Re: links in the OpenBSD FAQs
In message [EMAIL PROTECTED], Tom Cosgrove writes:
Don't create a bug report for this. This is not a bug. This is a
change of style that you (and some others) would like to see in the FAQ.
Nick, myself, and other people who work on the FAQ read misc@; there's
no point just pi**ing us off by calling this a bug.
Ok, I have not decided how this report must be classified yet. I will
read the type of reports carefully when submitting the patch. Thanks
a lot for your advice, indeed, it is a change of style, not a bug.
diff -urNp www/faq1.html www.new/faq1.html
--- www/faq1.html 2006-12-07 17:05:55.0 +0100
+++ www.new/faq1.html 2006-12-07 18:55:51.0 +0100
@@ -275,7 +275,8 @@ Theo de Raadt, located in Canada.
The OpenBSD team makes a new release every six months, with target release
dates in May and November. More information on the development cycle
-can be found a href=faq5.html#Flavorshere/a.
+can be found in the a href=faq5.html#FlavorsOpenBSD's Flavors/a
+subsection of this FAQ.
I personally find this clunky.
It now reads: More information... can be found in the OpenBSD's Flavors
subsection of this FAQ.
I am open to any advice. My english skills really need to be improved.
Now that I see that Nick do not want long links I would replace it
with just can be found in the flavours subsection, or something
like that (with the link in flavours).
I personally prefers something along the lines of More information...
can be found in section 5 of the FAQ. (with the link on section 5
of the FAQ) But Nick and I discuss changes like this backwards and
forwards quite a bit from time to time... that is why this is not a
mechanical set of changes, but one that requires a lot of effort and
no small ability with the English language
I considered writing that link as you like, but there is a problem with
this scheme: as the source code does not have references to labels (in
the sense TeX uses \ref{}) this change will scale poorly if the
section numbers change.
If it is ok, I will use the section numbers instead. It is certainly
better! But... will this change make the FAQ more difficult to maintain
if the section numbers change? If a section number changes, it is
not good manually fixing the references to that section in a lot of
places in the FAQ. That is the reason I am using the section titles
instead of numbers, section titles usually do not get outdated.
a name=Included/a
h21.8 - What is included with OpenBSD?/h2
@@ -362,7 +363,7 @@ Of course, additional applications can b
!-- XXXrelease --
The complete list of changes made to OpenBSD 3.9 to create OpenBSD 4.0
-can be found a href=../plus40.htmlhere/a, however here are a few
+can be found in the a href=../plus40.htmlOpenBSD 4.0 changes/a list,
however here are a few
Here I personally prefer ... can be found in plus40.html. (with the link
in the obvious place)
(i.e. sometimes the general form can be found at a href=xx/a.
works well. Especially since someone without an active link should be
able to find the target without undue searching - at least, if this
exercise is to be worthwhile).
Agreed, but the references to *.html files will be mostly useless
for people that, like me, use the text version of the FAQ. A link
like plus40.html depends on the structure of the FAQ (in this case,
the HTML files) that is not the same on all the formats.
Keep on with this, though
I will try to do my best to provide a good patch!
Many thanks
It is my pleasure being able to improve it. I really use the text
version of the FAQ and sometimes I miss better descriptions for
these click here links.
Cheers,
Igor.
Re: links in the OpenBSD FAQs
Nick Holland a icrit : Igor Sobrado wrote: I cannot see why making a patch to change the links is difficult. I will look at the cvs repository as soon as I get some time and submit a patch. In any case, I would appreciate a carefully review of it, just to fit it to the taste of the developers. Igor. It's harder than it looks (at least for me). Keep in mind, the PRIMARY usage by most readers is via web browser, so making it an awkward read to the majority so the text and PDF readers are happier is not really what I'm after. The result should be comfortably readable, not yelling at the reader, THE AUTHOR WAS WORKING HARD TO AVOID SAYING 'click _here_' AND WROTE THIS LONG, AWKWARD SENTENCE. W3C recommends to use clear and consistant link texts in their WAI guidelines [1]. This is especially important to people with cognitive disabilities or blindness, even if there might not be much of them in the OBSD world (but who knows), but benefit all users anyways. Moreover, links should be unique. This means that if you have several click here links (that's bad, but you already know) in one page, they should point to the same target. [1] http://www.w3.org/TR/WAI-WEBCONTENT (see 13.1) -- Ronnie Garcia r.garcia at ovea dot com
Re: links in the OpenBSD FAQs
Thanks a lot to all the people that provided feedback on this matter. Attached to this post is a new version of the patch. I did a mistake downloading the files used previously from the repository. This time, I choosed the right download method: $ cvs -d [EMAIL PROTECTED]:/cvs get www/faq The new patch is cleaner and much easier to review. Thanks a lot, again, for the excellent feedback. There are, however, some problems to be fixed: - some links (these to threads) are too large. - there are some references to manual pages that are not links. Cheers, Igor. diff -ur faq/faq1.html faq.new/faq1.html --- faq/faq1.html 2006-11-04 02:02:44.0 +0100 +++ faq.new/faq1.html 2006-12-08 01:31:16.0 +0100 @@ -275,7 +275,7 @@ The OpenBSD team makes a new release every six months, with target release dates in May and November. More information on the development cycle -can be found a href=faq5.html#Flavorshere/a. +can be found in the a href=faq5.html#FlavorsFAQ 5, OpenBSD's flavors/a section. a name=Included/a h21.8 - What is included with OpenBSD?/h2 @@ -362,7 +362,7 @@ !-- XXXrelease -- The complete list of changes made to OpenBSD 3.9 to create OpenBSD 4.0 -can be found a href=../plus40.htmlhere/a, however here are a few +can be found in the a href=../plus40.htmlOpenBSD 4.0 changes/a list, however here are a few changes the OpenBSD team anticipate will require or warrant some special note to people upgrading or installing OpenBSD 4.0 who are familiar with older versions: diff -ur faq/faq12.html faq.new/faq12.html --- faq/faq12.html 2006-11-01 04:07:32.0 +0100 +++ faq.new/faq12.html 2006-12-08 00:56:54.0 +0100 @@ -532,7 +532,7 @@ p The a href=http://simh.trailing-edge.com/;SIMH/a VAX simulator can be used to effectively emulate a real VAX. -Instructions can be found a href=../vax-simh.htmlhere/a. +Instructions can be found a href=../vax-simh.htmlOpenBSD/vax on SIMH/a page. p diff -ur faq/faq13.html faq.new/faq13.html --- faq/faq13.html 2006-11-01 06:06:03.0 +0100 +++ faq.new/faq13.html 2006-12-08 01:14:32.0 +0100 @@ -902,8 +902,8 @@ p The important thing is you use media which suit your DVD writer. If you expect compatibility with other DVD players, watch your step and -be sure to read -a href=http://www.dvddemystified.com/dvdfaq.html#4.3.1;this section/a +be sure to read the +a href=http://www.dvddemystified.com/dvdfaq.html#4.3.1;subsection 4.3.1/a of the DVD FAQ. h4DVD writing speed/h4 @@ -1281,9 +1281,8 @@ Some Real Audio streams can be made to work on i386 using bmplayer/b in conjunction with the ttgraphics/win32-codecs/tt and ttemulators/redhat/base/tt ports -(see -a href=http://marc.theaimsgroup.com/?t=10706051031amp;r=1amp;w=2;this -thread/a on the ports mailing list). +(see the thread +a href=http://marc.theaimsgroup.com/?t=10706051031amp;r=1amp;w=2;http://marc.theaimsgroup.com/?t=10706051031amp;r=1amp;w=2/a on the ports mailing list). a name=javaflash/a a name=javaplugin/a diff -ur faq/faq14.html faq.new/faq14.html --- faq/faq14.html 2006-11-09 04:36:59.0 +0100 +++ faq.new/faq14.html 2006-12-08 00:55:55.0 +0100 @@ -125,9 +125,9 @@ p There is not one right way to label a disk, but there are many wrong ways. -Before attempting to label your disk, see -a href=faq4.html#Partitioningthis discussion/a on partitioning and -partition sizing. +Before attempting to label your disk, see the +a href=faq4.html#Partitioningpartitioning and partition sizing/a +section. p For an example of using disklabel(8) during install, see the @@ -1669,8 +1669,8 @@ p Many OpenBSD a href=../plat.htmlplatforms/a include support for various hardware RAID products. The options vary by platform, see the -appropriate hardware support page (listed -a href=../plat.htmlhere/a). +appropriate hardware support page (listed in the +a href=../plat.htmlplatforms/a page). p Another option available for many platforms is one of the many products @@ -1851,8 +1851,7 @@ the native as well as the foreign filesystems was installed on the disk. However, if you install foreign filesystems after the OpenBSD disklabel was already installed on the disk, you need to add or modify them manually -afterwards. This will be explained in a href=#foreignfsafterthis -subsection/a. +afterwards. This will be explained a href=#foreignfsafterbelow/a. blockquotepre # bdisklabel wd0/b diff -ur faq/faq4.html faq.new/faq4.html --- faq/faq4.html 2006-12-03 05:03:00.0 +0100 +++ faq.new/faq4.html 2006-12-08 01:07:17.0 +0100 @@ -602,8 +602,8 @@ /ul !-- XXXversion -- -More information on upgrading between releases can be found -a href=upgrade40.htmlhere/a. +More information on upgrading between releases can be found on the +a href=upgrade40.htmlUpgrade Guide/a. libShell:/b Sometimes, you need to perform repairs or maintenance to a system which will not (or should not) boot to
Re: links in the OpenBSD FAQs
Igor Sobrado wrote: Nice to see that the text and PDF releases of the FAQ have finally been upgraded to 4.0... Just a suggestion: would it be possible replacing the links of the class ...can be found here (e.g., '1.7 of the OpenBSD FAQ) in the FAQs to more useful descriptions (e.g., ...can be found on the OpenBSD's Flavours section of the FAQ or ...can be found in the section 5.1 of the FAQ)? It is a minor trouble on formats that natively support links, but a major concern on the text version of the FAQs. Sure. Send a diff. Make it good. It's much easier to say something should be done better than to do it. Nick.
