From tfox at redhat.com Thu Jun 4 22:06:00 2015 Content-Type: multipart/mixed; boundary="===============0871353097286374738==" MIME-Version: 1.0 From: Tammy Fox To: docs at lists.fedoraproject.org Subject: draft notice text Date: Wed, 15 Sep 2004 16:52:56 -0400 Message-ID: <1095281576.6130.36.camel@jadefox.rdu.redhat.com> --===============0871353097286374738== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable I was about to add the common draft notice file from bug #132415, but I wanted to discuss the wording of the notice a bit more. (This was discussed on the Hardening Doc Preview thread, but I am starting a new one with a more appropriate subject.) The text proposed for the note is as follows: Draft Notice This version of this document is not yet affiliated with the Fedora= Docs Project. It is a draft, and may be submitted to the project for review/approval at a later date. Until that time, that document will be receiving constant updates, and may change frequently. Saying that it isn't affliliated with the Fedora Docs Project might be misleading. It is being worked on for the project, but it isn't final yet. Also, it would be nice to tell readers how to help with the document if they are reading it. So, how about the following: DRAFT This is a draft version of the document. It is subject to change = at any time and may not have been tested for technical accuracy = yet. If you find any errors, please report them via Bugzilla in bug = &BUG-NUM;. Then, in the parent file, the entity &BUG-NUM; would a link to the Bugzilla entry for that document. Thoughts? Tammy --===============0871353097286374738==-- From borgan at redhat.com Thu Jun 4 22:06:01 2015 Content-Type: multipart/mixed; boundary="===============8763362354856795981==" MIME-Version: 1.0 From: Brock Organ To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Wed, 15 Sep 2004 17:12:19 -0400 Message-ID: <1095282739.3483.4.camel@borgan.devel.redhat.com> In-Reply-To: 1095281576.6130.36.camel@jadefox.rdu.redhat.com --===============8763362354856795981== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Wed, 2004-09-15 at 16:52 -0400, Tammy Fox wrote: > I was about to add the common draft notice file from bug #132415, but I > wanted to discuss the wording of the notice a bit more. (This was > discussed on the Hardening Doc Preview thread, but I am starting a new > one with a more appropriate subject.) > = > Thoughts? sounds good to me ... Regards, Brock --===============8763362354856795981==-- From mjohnson at redhat.com Thu Jun 4 22:06:01 2015 Content-Type: multipart/mixed; boundary="===============0134456578854637739==" MIME-Version: 1.0 From: Mark Johnson To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Wed, 15 Sep 2004 17:38:15 -0400 Message-ID: <4148B647.9030305@redhat.com> In-Reply-To: 1095282739.3483.4.camel@borgan.devel.redhat.com --===============0134456578854637739== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Brock Organ wrote: > On Wed, 2004-09-15 at 16:52 -0400, Tammy Fox wrote: > = >>I was about to add the common draft notice file from bug #132415, but I >>wanted to discuss the wording of the notice a bit more. (This was >>discussed on the Hardening Doc Preview thread, but I am starting a new >>one with a more appropriate subject.) >> > = > = >>Thoughts? > = > = > sounds good to me ... Me, too. A nice improvement:) > Then, in the parent file, the entity &BUG-NUM; would a link to the > Bugzilla entry for that document. We may not want the &BUG-NUM; entity to show the full URL if it's = one of those horrendously long, page-wrapping bugzilla URLs. If = that's indeed the case, we may want the entity to contain a complete = ulink element with link text that is literally the bugzilla bug = number. ('just thinking out loud here...) Cheers, Mark -- = ---------------------------------------------------------- Mark Johnson OS Product Documentation Engineering, Red Hat, Inc. Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 --===============0134456578854637739==-- From paul at frields.com Thu Jun 4 22:06:01 2015 Content-Type: multipart/mixed; boundary="===============8387365281224988172==" MIME-Version: 1.0 From: Paul W. Frields To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Wed, 15 Sep 2004 18:19:15 -0400 Message-ID: <1095286755.4433.17.camel@bettie.internal.frields.org> In-Reply-To: 4148B647.9030305@redhat.com --===============8387365281224988172== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Wed, 2004-09-15 at 17:38, Mark Johnson wrote: > Brock Organ wrote: > > On Wed, 2004-09-15 at 16:52 -0400, Tammy Fox wrote: > > = > >>I was about to add the common draft notice file from bug #132415, but I > >>wanted to discuss the wording of the notice a bit more. (This was > >>discussed on the Hardening Doc Preview thread, but I am starting a new > >>one with a more appropriate subject.) > >> > >>Thoughts? > > = > > = > > sounds good to me ... > = > Me, too. A nice improvement:) I also like this! > > Then, in the parent file, the entity &BUG-NUM; would a link to the > > Bugzilla entry for that document. > = > We may not want the &BUG-NUM; entity to show the full URL if it's = > one of those horrendously long, page-wrapping bugzilla URLs. If = > that's indeed the case, we may want the entity to contain a complete = > ulink element with link text that is literally the bugzilla bug = > number. ('just thinking out loud here...) The URL always works in my experience (for non-restricted bugs of course). If the writer uses too long a URL, the editor can fix it without a problem. Or for that matter, I suppose we could have a common entity: And in the writer's doc: But maybe that's just too much work? Not sure. -- = Paul W. Frields, RHCE --===============8387365281224988172==-- From tuxxer at cox.net Thu Jun 4 22:06:01 2015 Content-Type: multipart/mixed; boundary="===============3078682341010941895==" MIME-Version: 1.0 From: tuxxer To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Wed, 15 Sep 2004 23:34:21 +0000 Message-ID: <1095291261.16202.194.camel@bach> In-Reply-To: 1095281576.6130.36.camel@jadefox.rdu.redhat.com --===============3078682341010941895== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Wed, 2004-09-15 at 20:52, Tammy Fox wrote: > I was about to add the common draft notice file from bug #132415, but I > wanted to discuss the wording of the notice a bit more. (This was > discussed on the Hardening Doc Preview thread, but I am starting a new > one with a more appropriate subject.) > = > The text proposed for the note is as follows: > = > > Draft Notice > This version of this document is not yet affiliated with the Fedo= ra Docs > Project. It is a draft, and may be submitted to the project for > review/approval at a later date. Until that time, that document will > be receiving constant updates, and may change frequently. > > > = > Saying that it isn't affliliated with the Fedora Docs Project might be > misleading. It is being worked on for the project, but it isn't final > yet. Also, it would be nice to tell readers how to help with the > document if they are reading it. So, how about the following: > = > > DRAFT > > This is a draft version of the document. It is subject to change = > at any time and may not have been tested for technical accuracy = > yet. If you find any errors, please report them via Bugzilla in bug = > &BUG-NUM;. > > > = > Then, in the parent file, the entity &BUG-NUM; would a link to the > Bugzilla entry for that document. > = > Thoughts? > = > Tammy I like the idea of the bugzilla reference. However, (in defense of my original draft [no pun intended]) IMHO a document isn't part of the FDP unless it's been committed to CVS (or is hosted or referenced by RedHat or Fedora). Would I be wrong in making this assumption? Nor is it in any way affiliated (other than by the author's "loyalty") with the project if it is hosted somewhere *other* than a RedHat/Fedora "official" site. Just from the little bit that I've seen since I've been here, this is not the general practice, nor is this functionality even available (I'm hosting my hardening "preview" on my own webspace [well.....my ISPs, but you get the idea]). I guess the point that I'm making here is this: A document is not part of the official documentation until it is fully "culled into the fold" of the FDP, e.g. accepted by the community and committed to CVS and/or hosted by RedHat/Fedora. How about a blend of the two approaches: Draft Notice This document is a draft. It is being developed for and/or by the $= FDP; community and is intended to be submitted as official documentation. = It is subject to change at any time and may not have been tested for = technical accuracy. If you find any errors, please report them via Bugzil= la in bug &BUG-NUM;. This closely resembles Tammy's proposal, but still implies that it has not been "blessed" by the community and, while it is still in draft form, is owned by the author (and not yet part of the official documentation). I don't mean to go off of the deep-end here. But (unless I missed something in the process) only those that are employed by RedHat are bound by any type of intellectual property rights (maybe not even then). So unless "volunteers" are going to be given certain "rights and privileges" (i.e. devel-cvs access, "preview" webspace, etc.), there's no obligation on the part of the author to develop and/or submit the document to/with the project. I don't mean to be antagonistic, I DO want to contribute to the community. But I guess the point I am ultimately making is, my words are my words, until I say (or it is mutually agreed upon) that they are NOT just *my* words. = The statement above (my proposed ammendment) implies, and/or states that it is not yet part of the official documentation, yet states intent, and therefore should be less misleading than the original text. I believe that also gives the community (and editors, and RedHat) a lot more "say-so" in the final presentation of that document. Otherwise, why even put any emphasis on the Project's "methods"? Why not write a document (in whatever format) and submit it? Just my 2 ...... ok, maybe .... 3 cents. ;) -Charlie -- = -- tuxxer <=3D=3D tuxxer's gpg key fingerprint =3D=3D> 57EB F948 76AE 25BC E340 EFA9 FAF6 E1AC F1E1 1EA1 --===============3078682341010941895== Content-Type: application/pgp-signature MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="signature.asc" LS0tLS1CRUdJTiBQR1AgU0lHTkFUVVJFLS0tLS0KVmVyc2lvbjogR251UEcgdjEuMi40IChHTlUv TGludXgpCgppRDhEQlFCQlNORjgrdmJoclBIaEhxRVJBbW1nQUo0NUgrRHlBcVJHb2o5NFNlVDRa V1AraDNIQXlBQ2ZlaUlxCmpUaTUvRlpIekZ3Zk5DNWFXMitpbWhzPQo9aDJpRgotLS0tLUVORCBQ R1AgU0lHTkFUVVJFLS0tLS0K --===============3078682341010941895==-- From kwade at redhat.com Thu Jun 4 22:06:01 2015 Content-Type: multipart/mixed; boundary="===============5828522469921315050==" MIME-Version: 1.0 From: Karsten Wade To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Thu, 16 Sep 2004 01:06:04 -0700 Message-ID: <1095321963.3014.64224.camel@erato.phig.org> In-Reply-To: 1095291261.16202.194.camel@bach --===============5828522469921315050== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Wed, 2004-09-15 at 16:34, tuxxer wrote: > > Thoughts? > > = > > Tammy > = > I like the idea of the bugzilla reference. However, (in defense of my > original draft [no pun intended]) IMHO a document isn't part of the FDP > unless it's been committed to CVS (or is hosted or referenced by RedHat > or Fedora). = I think the idea is that, yes, eventually, many authors will work on their documents directly in CVS. Think of the situation as being akin to a piece of software being made available during a test cycle. It is expected to be broken, but it's still part of Fedora. > How about a blend of the two approaches: Since both situations are likely to occur, why not offer both s as either/or options? I'd say that we could leave the wording entirely up to the author, but that would be presuming too much from writers. Still, if someone changed the wording in their doc for whatever reason, I don't think anyone would think it's a big deal. - Karsten -- = Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 --===============5828522469921315050==-- From kwade at redhat.com Thu Jun 4 22:06:01 2015 Content-Type: multipart/mixed; boundary="===============1620678394714673491==" MIME-Version: 1.0 From: Karsten Wade To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Thu, 16 Sep 2004 01:29:00 -0700 Message-ID: <1095323339.3014.64328.camel@erato.phig.org> In-Reply-To: 1095286755.4433.17.camel@bettie.internal.frields.org --===============1620678394714673491== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Wed, 2004-09-15 at 15:19, Paul W. Frields wrote: > On Wed, 2004-09-15 at 17:38, Mark Johnson wrote: > > Brock Organ wrote: > > > On Wed, 2004-09-15 at 16:52 -0400, Tammy Fox wrote: > > > = > > >>I was about to add the common draft notice file from bug #132415, but= I > > >>wanted to discuss the wording of the notice a bit more. (This was > > >>discussed on the Hardening Doc Preview thread, but I am starting a new > > >>one with a more appropriate subject.) > > >> > > >>Thoughts? > > > = > > > = > > > sounds good to me ... > > = > > Me, too. A nice improvement:) > = > I also like this! +1 for a complete consensus :) > The URL > always works in my experience (for non-restricted bugs of course). If > the writer uses too long a URL, the editor can fix it without a problem. > = > Or for that matter, I suppose we could have a common entity: > = > "http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=3D"> > = > And in the writer's doc: > = > Strike SYSTEM from that usage. > = > But maybe that's just too much work? Not sure. Seems simpler to go with a locally defined entity that is the bug #. FWIW, this works: http://bugzilla.redhat.com/XXXXXX I think Mark is thinking of a pre-filled bug report such as the one that I use for the SELinux FAQ. For getting proper feedback, it is invaluable -- it prefills the product, version, and component, sets the blocker bug and assigned to, suggests a useful title-style, should have the latest version number embedded already, and has specific suggestions for filling out a bug report unique to this project. However, it looks like this: https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=3DFedora%20Core&= op_sys=3DLinux&version=3Dfc3test2&component=3Dfedora-docs&component_text=3D= &rep_platform=3DAll&priority=3Dnormal&bug_severity=3Dnormal&bug_status=3DNE= W&assigned_to=3Dkwade%40redhat.com&cc=3D&estimated_time=3D0.0&bug_file_loc= =3Dhttp%3A%2F%2Fpeople.redhat.com%2Fkwade%2Ffedora-docs%2Fselinux-faq-en%2F= &short_desc=3DSELinux%20FAQ%20-%20%5Bsummarize%20FAQ%20change%20or%20additi= on%5D&comment=3DDescription%20of%20change%2FFAQ%20addition.%20%20If%20a%20c= hange%2C%20include%20the%20original%0D%0Atext%20first%2C%20then%20the%20cha= nged%20text%3A%0D%0A%0D%0A%0D%0A%0D%0AVersion-Release%20of%20FAQ%20%28found= %20on%0D%0Ahttp%3A%2F%2Fpeople.redhat.com%2Fkwade%2Ffedora-docs%2Fselinux-f= aq-en%2Fln-legalnotice.html%29%3A%0D%0A%0D%0A%20for%20example%3A%20selinux-= faq-1.3%20%282004-09-15-T04%3A20-0800%29%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%0D%0= A%0D%0A%0D%0A%0D%0A&keywords=3D&dependson=3D&blocked=3D118757%20%20&maketem= plate=3DRemember%20values%20as%20bookmarkable%20templ! ate&form_name=3Denter_bug I use a with descriptive link text. :) How about: 1. If it is just a link to the bug report, then: usage: 2. If it is a Really Long URL, then following the same solution to define the entity, but usage is: pre-filled bug report NOTE - if you use a long URL that includes '&' characters, you _must_ change them to & in the XML so that they process into the correct characters when rendered. - Karsten -- = Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 --===============1620678394714673491==-- From kwade at redhat.com Thu Jun 4 22:06:01 2015 Content-Type: multipart/mixed; boundary="===============2020657314622978343==" MIME-Version: 1.0 From: Karsten Wade To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Thu, 16 Sep 2004 01:39:50 -0700 Message-ID: <1095323989.3014.64368.camel@erato.phig.org> In-Reply-To: 1095323339.3014.64328.camel@erato.phig.org --===============2020657314622978343== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Thu, 2004-09-16 at 01:29, Karsten Wade wrote: > 2. If it is a Really Long URL, then following the same solution to > define the entity, but usage is: > = > pre-filled bug report > = > NOTE - if you use a long URL that includes '&' characters, you _must_ > change them to & in the XML so that they process into the correct > characters when rendered. Oops ... looks like there are plenty of special characters that have other meaning in the ENTITY space, such as %. I tried to do option 2., and the build broke on the %. I had to change 97 % to % ... and it worked. - Karsten -- = Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 --===============2020657314622978343==-- From paul at frields.com Thu Jun 4 22:06:01 2015 Content-Type: multipart/mixed; boundary="===============2455506272436939840==" MIME-Version: 1.0 From: Paul W. Frields To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Thu, 16 Sep 2004 09:55:15 -0400 Message-ID: <1095342914.2361.3.camel@berlin.east.gov> In-Reply-To: 1095323989.3014.64368.camel@erato.phig.org --===============2455506272436939840== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Thu, 2004-09-16 at 04:39, Karsten Wade wrote: > > 2. If it is a Really Long URL, then following the same solution to > > define the entity, but usage is: > > = > > pre-filled bug report > > = > > NOTE - if you use a long URL that includes '&' characters, you _must_ > > change them to & in the XML so that they process into the correct > > characters when rendered. > = > Oops ... looks like there are plenty of special characters that have > other meaning in the ENTITY space, such as %. I tried to do option 2., > and the build broke on the %. > = > I had to change 97 % to % ... and it worked. I agree with the approach, and with the usage. One question: for Very Long URLs, should the actual URL appear somewhere like a ? Normally we use the URL as the content body as well as the "url" parameter for . I like the idea that people will be able to read the document online and immediately register problems if they have any. Customer service at its finest! -- = Paul W. Frields, RHCE --===============2455506272436939840==-- From kwade at redhat.com Thu Jun 4 22:06:02 2015 Content-Type: multipart/mixed; boundary="===============7633368299351221454==" MIME-Version: 1.0 From: Karsten Wade To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Thu, 16 Sep 2004 09:28:15 -0700 Message-ID: <1095352094.3014.65780.camel@erato.phig.org> In-Reply-To: 1095342914.2361.3.camel@berlin.east.gov --===============7633368299351221454== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Thu, 2004-09-16 at 06:55, Paul W. Frields wrote: > I agree with the approach, and with the usage. One question: for Very > Long URLs, should the actual URL appear somewhere like a ? > Normally we use the URL as the content body as well as the "url" > parameter for . Ideally, you wouldn't have to do this. When rendered to HTML, a should make a hyperlink, and when rendered to print (PDF), a footnote should be generated instead (and it should wrap properly, too.) However, the PDF part has been broken in SGML in our internal toolchain for some time, which is what prompted the practice in the Doc Guide. Is this still broken in the FDP toolchain? I don't have a working PDF build at the moment (again) to test ... - Karsten -- = Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 --===============7633368299351221454==-- From paul at frields.com Thu Jun 4 22:06:02 2015 Content-Type: multipart/mixed; boundary="===============3346331238169522033==" MIME-Version: 1.0 From: Paul W. Frields To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Thu, 16 Sep 2004 14:22:38 -0400 Message-ID: <1095358958.3730.0.camel@berlin.east.gov> In-Reply-To: 1095352094.3014.65780.camel@erato.phig.org --===============3346331238169522033== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Thu, 2004-09-16 at 12:28, Karsten Wade wrote: > On Thu, 2004-09-16 at 06:55, Paul W. Frields wrote: > = > > I agree with the approach, and with the usage. One question: for Very > > Long URLs, should the actual URL appear somewhere like a ? > > Normally we use the URL as the content body as well as the "url" > > parameter for . > = > Ideally, you wouldn't have to do this. When rendered to HTML, a > should make a hyperlink, and when rendered to print (PDF), a > footnote should be generated instead (and it should wrap properly, too.) That's what I was looking for, thanks. > However, the PDF part has been broken in SGML in our internal toolchain > for some time, which is what prompted the practice in the Doc Guide. > = > Is this still broken in the FDP toolchain? I don't have a working PDF > build at the moment (again) to test ... I'll test and let you know. My PDF builds work fine, albeit to A4 paper size. -- = Paul W. Frields, RHCE --===============3346331238169522033==-- From tfox at redhat.com Thu Jun 4 22:06:02 2015 Content-Type: multipart/mixed; boundary="===============4988521132033806677==" MIME-Version: 1.0 From: Tammy Fox To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Fri, 17 Sep 2004 11:15:47 -0400 Message-ID: <1095434146.6112.9.camel@jadefox.rdu.redhat.com> In-Reply-To: 4148B647.9030305@redhat.com --===============4988521132033806677== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Wed, 2004-09-15 at 17:38, Mark Johnson wrote: > Brock Organ wrote: > > On Wed, 2004-09-15 at 16:52 -0400, Tammy Fox wrote: > > = > >>I was about to add the common draft notice file from bug #132415, but I > >>wanted to discuss the wording of the notice a bit more. (This was > >>discussed on the Hardening Doc Preview thread, but I am starting a new > >>one with a more appropriate subject.) > >> > > = > > = > >>Thoughts? > > = > > = > > sounds good to me ... > = > Me, too. A nice improvement:) > = > > Then, in the parent file, the entity &BUG-NUM; would a link to the > > Bugzilla entry for that document. > = > We may not want the &BUG-NUM; entity to show the full URL if it's = > one of those horrendously long, page-wrapping bugzilla URLs. If = > that's indeed the case, we may want the entity to contain a complete = > ulink element with link text that is literally the bugzilla bug = > number. ('just thinking out loud here...) > = > Cheers, > Mark > = > = Sorry. That is what I was thinking but just didn't articulate properly. The HTML version would have a link, but the text itself would just have the bug number such as: If you find any errors, please report them via Bugzilla in bug #11111. Tammy > -- = > ---------------------------------------------------------- > Mark Johnson > OS Product Documentation > Engineering, Red Hat, Inc. > Tel: 919.754.4151 Fax: 919.754.3708 > GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 > = --===============4988521132033806677==-- From tfox at redhat.com Thu Jun 4 22:06:02 2015 Content-Type: multipart/mixed; boundary="===============3289614759967213693==" MIME-Version: 1.0 From: Tammy Fox To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Fri, 17 Sep 2004 11:21:20 -0400 Message-ID: <1095434479.6112.13.camel@jadefox.rdu.redhat.com> In-Reply-To: 1095352094.3014.65780.camel@erato.phig.org --===============3289614759967213693== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Thu, 2004-09-16 at 12:28, Karsten Wade wrote: > On Thu, 2004-09-16 at 06:55, Paul W. Frields wrote: > = > > I agree with the approach, and with the usage. One question: for Very > > Long URLs, should the actual URL appear somewhere like a ? > > Normally we use the URL as the content body as well as the "url" > > parameter for . > = > Ideally, you wouldn't have to do this. When rendered to HTML, a > should make a hyperlink, and when rendered to print (PDF), a > footnote should be generated instead (and it should wrap properly, too.) > = > However, the PDF part has been broken in SGML in our internal toolchain > for some time, which is what prompted the practice in the Doc Guide. > = What part is broken? The footnote for URLs? I turned that off on purpose in our stylesheets for our internal SGML because we decided that we preferred the URL inline or inside screen tags if it might line wrap. Tammy > Is this still broken in the FDP toolchain? I don't have a working PDF > build at the moment (again) to test ... > = > - Karsten > -- = > Karsten Wade, RHCE, Tech Writer > a lemon is just a melon in disguise > http://people.redhat.com/kwade/ > gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 > = --===============3289614759967213693==-- From tfox at redhat.com Thu Jun 4 22:06:02 2015 Content-Type: multipart/mixed; boundary="===============2292860219281525465==" MIME-Version: 1.0 From: Tammy Fox To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Fri, 17 Sep 2004 11:23:57 -0400 Message-ID: <1095434637.6112.17.camel@jadefox.rdu.redhat.com> In-Reply-To: 1095342914.2361.3.camel@berlin.east.gov --===============2292860219281525465== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Thu, 2004-09-16 at 09:55, Paul W. Frields wrote: > On Thu, 2004-09-16 at 04:39, Karsten Wade wrote: > > > 2. If it is a Really Long URL, then following the same solution to > > > define the entity, but usage is: > > > = > > > pre-filled bug report > > > = > > > NOTE - if you use a long URL that includes '&' characters, you _must_ > > > change them to & in the XML so that they process into the correct > > > characters when rendered. > > = > > Oops ... looks like there are plenty of special characters that have > > other meaning in the ENTITY space, such as %. I tried to do option 2., > > and the build broke on the %. > > = > > I had to change 97 % to % ... and it worked. > = > I agree with the approach, and with the usage. One question: for Very > Long URLs, should the actual URL appear somewhere like a ? > Normally we use the URL as the content body as well as the "url" > parameter for . > = > I like the idea that people will be able to read the document online and > immediately register problems if they have any. Customer service at its > finest! > = > -- = > Paul W. Frields, RHCE > = For docs created for RHEL, etc. we decided that the URL should be part of the text since when the decision was made we printed the docs. So, our rule was, if the URL is short, it should be inline text. If it is long and might line wrap, include it in screen tags so it is always rendered on its own line. Tammy --===============2292860219281525465==-- From paul at frields.com Thu Jun 4 22:06:02 2015 Content-Type: multipart/mixed; boundary="===============0614851622967974179==" MIME-Version: 1.0 From: Paul W. Frields To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Fri, 17 Sep 2004 11:32:25 -0400 Message-ID: <1095435145.4419.6.camel@berlin.east.gov> In-Reply-To: 1095434637.6112.17.camel@jadefox.rdu.redhat.com --===============0614851622967974179== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Fri, 2004-09-17 at 11:23, Tammy Fox wrote: > For docs created for RHEL, etc. we decided that the URL should be part > of the text since when the decision was made we printed the docs. So, > our rule was, if the URL is short, it should be inline text. If it is > long and might line wrap, include it in screen tags so it is always > rendered on its own line. Would you say that the suggested usage is OK, since it is doubtful these manuals will be printed commercially? I would expect users *might* print them locally for reference, but most reading will be done online, I suspect, whether off a local hard disk (installed from a fedora-docs[1] RPM package) or the Internet. If we can turn the footnote function back on for Fedora, that would be great IMHO. Also, I have another minor suggestion (I think for the stylesheets) which I will post to the list and bugzilla momentarily. =3D =3D =3D =3D =3D [1] Hmm, maybe fedora-docs-{html,pdf[,others?]} -- = Paul W. Frields, RHCE --===============0614851622967974179==-- From tfox at redhat.com Thu Jun 4 22:06:02 2015 Content-Type: multipart/mixed; boundary="===============0396631841030645294==" MIME-Version: 1.0 From: Tammy Fox To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Fri, 17 Sep 2004 12:17:05 -0400 Message-ID: <1095437825.6112.70.camel@jadefox.rdu.redhat.com> In-Reply-To: 1095323339.3014.64328.camel@erato.phig.org --===============0396631841030645294== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Thu, 2004-09-16 at 04:29, Karsten Wade wrote: > On Wed, 2004-09-15 at 15:19, Paul W. Frields wrote: > > On Wed, 2004-09-15 at 17:38, Mark Johnson wrote: > > > Brock Organ wrote: > > > > On Wed, 2004-09-15 at 16:52 -0400, Tammy Fox wrote: > > > > = > > > >>I was about to add the common draft notice file from bug #132415, b= ut I > > > >>wanted to discuss the wording of the notice a bit more. (This was > > > >>discussed on the Hardening Doc Preview thread, but I am starting a = new > > > >>one with a more appropriate subject.) > > > >> > > > >>Thoughts? > > > > = > > > > = > > > > sounds good to me ... > > > = > > > Me, too. A nice improvement:) > > = > > I also like this! > = > +1 for a complete consensus :) Then let it be so. I've added this to CVS and closed out the bug. Thanks for the feedback. Tammy > = > > The URL > > always works in my experience (for non-restricted bugs of course). If > > the writer uses too long a URL, the editor can fix it without a problem. > > = > > Or for that matter, I suppose we could have a common entity: > > = > > > "http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=3D"> > > = > > And in the writer's doc: > > = > > > = > Strike SYSTEM from that usage. > = > > = > > But maybe that's just too much work? Not sure. > = > Seems simpler to go with a locally defined entity that is the bug #. > = > FWIW, this works: http://bugzilla.redhat.com/XXXXXX > = > I think Mark is thinking of a pre-filled bug report such as the one that > I use for the SELinux FAQ. For getting proper feedback, it is > invaluable -- it prefills the product, version, and component, sets the > blocker bug and assigned to, suggests a useful title-style, should have > the latest version number embedded already, and has specific suggestions > for filling out a bug report unique to this project. However, it looks > like this: > = > https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=3DFedora%20Cor= e&op_sys=3DLinux&version=3Dfc3test2&component=3Dfedora-docs&component_text= =3D&rep_platform=3DAll&priority=3Dnormal&bug_severity=3Dnormal&bug_status= =3DNEW&assigned_to=3Dkwade%40redhat.com&cc=3D&estimated_time=3D0.0&bug_file= _loc=3Dhttp%3A%2F%2Fpeople.redhat.com%2Fkwade%2Ffedora-docs%2Fselinux-faq-e= n%2F&short_desc=3DSELinux%20FAQ%20-%20%5Bsummarize%20FAQ%20change%20or%20ad= dition%5D&comment=3DDescription%20of%20change%2FFAQ%20addition.%20%20If%20a= %20change%2C%20include%20the%20original%0D%0Atext%20first%2C%20then%20the%2= 0changed%20text%3A%0D%0A%0D%0A%0D%0A%0D%0AVersion-Release%20of%20FAQ%20%28f= ound%20on%0D%0Ahttp%3A%2F%2Fpeople.redhat.com%2Fkwade%2Ffedora-docs%2Fselin= ux-faq-en%2Fln-legalnotice.html%29%3A%0D%0A%0D%0A%20for%20example%3A%20seli= nux-faq-1.3%20%282004-09-15-T04%3A20-0800%29%0D%0A%0D%0A%0D%0A%0D%0A%0D%0A%= 0D%0A%0D%0A%0D%0A%0D%0A&keywords=3D&dependson=3D&blocked=3D118757%20%20&mak= etemplate=3DRemember%20values%20as%20bookmarkable%20tem! pl! > ate&form_name=3Denter_bug > = > I use a with descriptive link text. :) > = > How about: > = > 1. If it is just a link to the bug report, then: > = > > = > usage: > = > > = > 2. If it is a Really Long URL, then following the same solution to > define the entity, but usage is: > = > pre-filled bug report > = > NOTE - if you use a long URL that includes '&' characters, you _must_ > change them to & in the XML so that they process into the correct > characters when rendered. > = > - Karsten > -- = > Karsten Wade, RHCE, Tech Writer > a lemon is just a melon in disguise > http://people.redhat.com/kwade/ > gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 > = --===============0396631841030645294==-- From tfox at redhat.com Thu Jun 4 22:06:02 2015 Content-Type: multipart/mixed; boundary="===============6750432602497919091==" MIME-Version: 1.0 From: Tammy Fox To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Fri, 17 Sep 2004 12:24:53 -0400 Message-ID: <1095438293.6112.79.camel@jadefox.rdu.redhat.com> In-Reply-To: 1095435145.4419.6.camel@berlin.east.gov --===============6750432602497919091== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Fri, 2004-09-17 at 11:32, Paul W. Frields wrote: > On Fri, 2004-09-17 at 11:23, Tammy Fox wrote: > > For docs created for RHEL, etc. we decided that the URL should be part > > of the text since when the decision was made we printed the docs. So, > > our rule was, if the URL is short, it should be inline text. If it is > > long and might line wrap, include it in screen tags so it is always > > rendered on its own line. > = > Would you say that the suggested usage is OK, since it is doubtful these > manuals will be printed commercially? I would expect users *might* print > them locally for reference, but most reading will be done online, I > suspect, whether off a local hard disk (installed from a fedora-docs[1] > RPM package) or the Internet. > = Sure. I think most of the Fedora docs are going to be read from their HTML versions. So, I don't see any problem with having the URLs rendered as footnotes in the PDF versions. It might look a little weird if the text inside the ulink tags is the actual URL, but I don't think that is a big deal for the Fedora docs. I don't recall turning off footnotes in the Fedora stylesheets, so I'll look at it to make sure it is still rendering them for PDF versions. Do we want the footnotes to show up in the HTML versions as well? I don't think they do by default. My vote is not to show the footnotes in the HTML. Tammy > If we can turn the footnote function back on for Fedora, that would be > great IMHO. Also, I have another minor suggestion (I think for the > stylesheets) which I will post to the list and bugzilla momentarily. > = > =3D =3D =3D =3D =3D > [1] Hmm, maybe fedora-docs-{html,pdf[,others?]} > = Couldn't resist using a footnote in a post about footnotes huh? ;-) Tammy > -- = > Paul W. Frields, RHCE --===============6750432602497919091==-- From tfox at redhat.com Thu Jun 4 22:06:02 2015 Content-Type: multipart/mixed; boundary="===============3140721396155209339==" MIME-Version: 1.0 From: Tammy Fox To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Fri, 17 Sep 2004 12:35:59 -0400 Message-ID: <1095438958.6112.88.camel@jadefox.rdu.redhat.com> In-Reply-To: 1095438293.6112.79.camel@jadefox.rdu.redhat.com --===============3140721396155209339== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Fri, 2004-09-17 at 12:24, Tammy Fox wrote: > On Fri, 2004-09-17 at 11:32, Paul W. Frields wrote: > > On Fri, 2004-09-17 at 11:23, Tammy Fox wrote: > > > For docs created for RHEL, etc. we decided that the URL should be part > > > of the text since when the decision was made we printed the docs. So, > > > our rule was, if the URL is short, it should be inline text. If it is > > > long and might line wrap, include it in screen tags so it is always > > > rendered on its own line. > > = > > Would you say that the suggested usage is OK, since it is doubtful these > > manuals will be printed commercially? I would expect users *might* print > > them locally for reference, but most reading will be done online, I > > suspect, whether off a local hard disk (installed from a fedora-docs[1] > > RPM package) or the Internet. > > = > = > Sure. I think most of the Fedora docs are going to be read from their > HTML versions. So, I don't see any problem with having the URLs rendered > as footnotes in the PDF versions. It might look a little weird if the > text inside the ulink tags is the actual URL, but I don't think that is > a big deal for the Fedora docs. I don't recall turning off footnotes in > the Fedora stylesheets, so I'll look at it to make sure it is still > rendering them for PDF versions. > = The default behavior for PDFs is to put the URL in brackets: some link [http://www.example.com/] For HTML, it just creates the href without a footnote or brackets. The brackets don't look that bad, but if the URL is too long, it doesn't line wrap. It just goes off the page. We had this problem with DSSSL and SGML for a while, but it was eventually fixed. So, it looks like footnotes in the PDFs are the way to go. Please file an RFE, and I'll look into it unless someone already knows the XSLT to add footnotes for URLs in the PDF output. Tammy > Do we want the footnotes to show up in the HTML versions as well? I > don't think they do by default. My vote is not to show the footnotes in > the HTML. > = > Tammy > = > = > > If we can turn the footnote function back on for Fedora, that would be > > great IMHO. Also, I have another minor suggestion (I think for the > > stylesheets) which I will post to the list and bugzilla momentarily. > > = > > =3D =3D =3D =3D =3D > > [1] Hmm, maybe fedora-docs-{html,pdf[,others?]} > > = > = > Couldn't resist using a footnote in a post about footnotes huh? ;-) > = > Tammy > = > > -- = > > Paul W. Frields, RHCE > = > = --===============3140721396155209339==-- From paul at frields.com Thu Jun 4 22:06:03 2015 Content-Type: multipart/mixed; boundary="===============1436312522409276106==" MIME-Version: 1.0 From: Paul W. Frields To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Fri, 17 Sep 2004 12:41:25 -0400 Message-ID: <1095439285.4419.40.camel@berlin.east.gov> In-Reply-To: 1095438293.6112.79.camel@jadefox.rdu.redhat.com --===============1436312522409276106== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Fri, 2004-09-17 at 12:24, Tammy Fox wrote: > On Fri, 2004-09-17 at 11:32, Paul W. Frields wrote: > > On Fri, 2004-09-17 at 11:23, Tammy Fox wrote: > > > For docs created for RHEL, etc. we decided that the URL should be part > > > of the text since when the decision was made we printed the docs. So, > > > our rule was, if the URL is short, it should be inline text. If it is > > > long and might line wrap, include it in screen tags so it is always > > > rendered on its own line. > > = > > Would you say that the suggested usage is OK, since it is doubtful these > > manuals will be printed commercially? I would expect users *might* print > > them locally for reference, but most reading will be done online, I > > suspect, whether off a local hard disk (installed from a fedora-docs[1] > > RPM package) or the Internet. > > = > = > Sure. I think most of the Fedora docs are going to be read from their > HTML versions. So, I don't see any problem with having the URLs rendered > as footnotes in the PDF versions. It might look a little weird if the > text inside the ulink tags is the actual URL, but I don't think that is > a big deal for the Fedora docs. I don't recall turning off footnotes in > the Fedora stylesheets, so I'll look at it to make sure it is still > rendering them for PDF versions. Thanks, I haven't had a chance yet. > Do we want the footnotes to show up in the HTML versions as well? I > don't think they do by default. My vote is not to show the footnotes in > the HTML. I agree. > > If we can turn the footnote function back on for Fedora, that would be > > great IMHO. Also, I have another minor suggestion (I think for the > > stylesheets) which I will post to the list and bugzilla momentarily. > > = > > =3D =3D =3D =3D =3D > > [1] Hmm, maybe fedora-docs-{html,pdf[,others?]} > > = > Couldn't resist using a footnote in a post about footnotes huh? ;-) No, but fortunately I *could* resist doing it in this reply to a post about a footnote in a post about footnotes! (Sorry, loopy from lack of lunch.[1]) =3D =3D =3D =3D =3D [1] Should that be a new acronym, "LLL"? Oh no, I broke my vow of footnotelessness! AAAAGGHH! :-( :-D -- = Paul W. Frields, RHCE --===============1436312522409276106==-- From davep at dpawson.co.uk Thu Jun 4 22:06:03 2015 Content-Type: multipart/mixed; boundary="===============8006870433917663764==" MIME-Version: 1.0 From: Dave Pawson To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Fri, 17 Sep 2004 18:51:46 +0100 Message-ID: <1095443505.2518.11.camel@homer> In-Reply-To: 1095435145.4419.6.camel@berlin.east.gov --===============8006870433917663764== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Fri, 2004-09-17 at 16:32, Paul W. Frields wrote: > If we can turn the footnote function back on for Fedora, that would be > great IMHO. Is this project obligued to keep in step with rhel? I see it drifting further and further from docbook. Clinging to sgml is plain daft IMHO. When docbook 5 comes out will it remain with the SGML DTD? What's the objection to keeping up to date? = -- = Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl --===============8006870433917663764==-- From tfox at redhat.com Thu Jun 4 22:06:03 2015 Content-Type: multipart/mixed; boundary="===============1179563511686849566==" MIME-Version: 1.0 From: Tammy Fox To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Fri, 17 Sep 2004 15:21:15 -0400 Message-ID: <1095448875.6112.125.camel@jadefox.rdu.redhat.com> In-Reply-To: 1095443505.2518.11.camel@homer --===============1179563511686849566== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Fri, 2004-09-17 at 13:51, Dave Pawson wrote: > On Fri, 2004-09-17 at 16:32, Paul W. Frields wrote: > = > > If we can turn the footnote function back on for Fedora, that would be > > great IMHO. > = > Is this project obligued to keep in step with rhel? > = > I see it drifting further and further from docbook. > Clinging to sgml is plain daft IMHO. > = > When docbook 5 comes out will it remain with the SGML DTD? > What's the objection to keeping up to date? > = > = > -- = > Regards DaveP. > XSLT&Docbook FAQ > http://www.dpawson.co.uk/xsl > = > = No. We are not obligated to keep in step with RHEL. We are using a different toolchain and can agree to upgrade to DocBook 5 when it comes out if we want to. When a question comes up, I have been mentioning how we solved the problem internally with our DocBook SGML toolchain to offer a solution. Sometimes we agree to do the same thing. Sometimes we agree to do something different. Tammy --===============1179563511686849566==-- From kwade at redhat.com Thu Jun 4 22:06:03 2015 Content-Type: multipart/mixed; boundary="===============8216964089356000992==" MIME-Version: 1.0 From: Karsten Wade To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Fri, 17 Sep 2004 13:13:18 -0700 Message-ID: <1095451997.4078.281.camel@erato.phig.org> In-Reply-To: 1095434479.6112.13.camel@jadefox.rdu.redhat.com --===============8216964089356000992== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Fri, 2004-09-17 at 08:21, Tammy Fox wrote: > What part is broken? The footnote for URLs? I turned that off on purpose > in our stylesheets for our internal SGML because we decided that we > preferred the URL inline or inside screen tags if it might line wrap. I now recall working with Tim Waugh to resolve PDF conversion issues with URLs in blocks not wrapping. I was putting URLs in footnotes manually because they wouldn't appear by themselves in PDF as footnotes (inline or in blocks was not an option). It may have never occurred to me to ask about that, I might have assumed it was broken. Oh, well. :) - Karsten -- = Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 --===============8216964089356000992==-- From kwade at redhat.com Thu Jun 4 22:06:03 2015 Content-Type: multipart/mixed; boundary="===============8154997447081158426==" MIME-Version: 1.0 From: Karsten Wade To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Fri, 17 Sep 2004 13:19:47 -0700 Message-ID: <1095452387.4078.311.camel@erato.phig.org> In-Reply-To: 1095448875.6112.125.camel@jadefox.rdu.redhat.com --===============8154997447081158426== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Fri, 2004-09-17 at 12:21, Tammy Fox wrote: > On Fri, 2004-09-17 at 13:51, Dave Pawson wrote: > > On Fri, 2004-09-17 at 16:32, Paul W. Frields wrote: > > = > > > If we can turn the footnote function back on for Fedora, that would be > > > great IMHO. > > = > > Is this project obligued to keep in step with rhel? > > = > = > No. We are not obligated to keep in step with RHEL. We are using a > different toolchain and can agree to upgrade to DocBook 5 when it comes > out if we want to. When a question comes up, I have been mentioning how > we solved the problem internally with our DocBook SGML toolchain to > offer a solution. Sometimes we agree to do the same thing. Sometimes we > agree to do something different. I bring up items about the RHEL toolchain to explain the history behind a practice, which may tie in with discovering how it something works better or different in XMLS DocBook. The internal toolchain is very different from the one we are using in FDP. Point of fact, this project may define the future of the RHEL toolchain, in much the same way that Fedora Core influences RHEL. This explains some of why I personally am wrestling with these issues, I'll be working with the decisions we make now for years to come. :) - Karsten -- = Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 --===============8154997447081158426==-- From davep at dpawson.co.uk Thu Jun 4 22:06:03 2015 Content-Type: multipart/mixed; boundary="===============4255031720205663816==" MIME-Version: 1.0 From: Dave Pawson To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Sat, 18 Sep 2004 13:24:57 +0100 Message-ID: <1095510296.2538.9.camel@homer> In-Reply-To: 1095448875.6112.125.camel@jadefox.rdu.redhat.com --===============4255031720205663816== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Fri, 2004-09-17 at 20:21, Tammy Fox wrote: > = > No. We are not obligated to keep in step with RHEL. We are using a > different toolchain and can agree to upgrade to DocBook 5 when it comes > out if we want to. When a question comes up, I have been mentioning how > we solved the problem internally with our DocBook SGML toolchain to > offer a solution. Sometimes we agree to do the same thing. Sometimes we > agree to do something different. What rationale is there for remaining with the SGML toolchain? -- = Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl --===============4255031720205663816==-- From kwade at redhat.com Thu Jun 4 22:06:03 2015 Content-Type: multipart/mixed; boundary="===============8825868400078165196==" MIME-Version: 1.0 From: Karsten Wade To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Sat, 18 Sep 2004 11:06:05 -0700 Message-ID: <1095530764.4078.5271.camel@erato.phig.org> In-Reply-To: 1095510296.2538.9.camel@homer --===============8825868400078165196== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Sat, 2004-09-18 at 05:24, Dave Pawson wrote: > What rationale is there for remaining with the SGML toolchain? Ironically, the same reason that businesses worldwide stick with old-but-working systems, where working =3D=3D we hacked it to work well enough to ship. For the time to produce Enterprise Linux 4, we didn't have enough cycles to do the R&D ourselves and start writing our guides for the next release. There are significant cross-team constraints, such as having percentages of guides string and code frozen for the translation team to work on. Frankly, it was pretty daunting to imagine doing the XML toolchain all ourselves. At the time that we had to choose go/no-go on switching to XML, there were too many problems in the community tools (xmlto PDF conversion being a big one, iirc), so we had to stick with SGML. Once we started working in SGML for the production release, we had to stick with it all the way through until release. However, and here is the double-good news: because of all the good work we are doing here proving the capabilities and readiness of the latest DocBook using XML, those of us who are writing new guides (i.e., no legacy SGML) _and_ who are not being translated will get to choose to use a parallel XML toolchain based on the FDP tools for the Enterprise Linux 4 release ... well, probably nearly exactly the FDP tools with our XSL or DSSSL (again, prepared to use DSSSL just in case we can't pull the trigger on XSL in time). That means I'm writing 100% in XML, as soon as I take the few hours to convert my existing work from SGML. :-) - Karsten -- = Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 --===============8825868400078165196==-- From mjohnson at redhat.com Thu Jun 4 22:06:03 2015 Content-Type: multipart/mixed; boundary="===============1173831367589404369==" MIME-Version: 1.0 From: Mark Johnson To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Sat, 18 Sep 2004 14:19:48 -0400 Message-ID: <414C7C44.50501@redhat.com> In-Reply-To: 1095530764.4078.5271.camel@erato.phig.org --===============1173831367589404369== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Karsten Wade wrote: > On Sat, 2004-09-18 at 05:24, Dave Pawson wrote: > = > = >>What rationale is there for remaining with the SGML toolchain? > = > However, and here is the double-good news: because of all the good work > we are doing here proving the capabilities and readiness of the latest > DocBook using XML, = > those of us who are writing new guides (i.e., no > legacy SGML) _and_ who are not being translated = FWIW, this includes me. I *only* write in XML. > will get to choose to > use a parallel XML toolchain based on the FDP tools for the Enterprise > Linux 4 release ... well, probably nearly exactly the FDP tools with our > XSL = This is the hope, anyway. FDP certainly provides an excellent test = case for a given toolchain. However, we may end up with something entirely different, like a = java-based system. We may, e.g., decide that Saxon is more appropriate as an XSLT = processor (due to its docbook & other extensions), and that FOP is = adequate for our FO --> PDF needs, instead of having to revert to = the tried & true jade/DSSSL combo for PDF output. XSLT and XSL-FO = are simply easier to deal with than is DSSSL. At any rate, we won't be committing to any new toolchain (and = changing all RHEL docs over to XML) until after RHEL4 is released. My $0.02, Mark > That means I'm writing 100% in XML, as soon as I take the few hours to > convert my existing work from SGML. :-) > = > - Karsten -- = ---------------------------------------------------------- Mark Johnson OS Product Documentation Engineering, Red Hat, Inc. Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 --===============1173831367589404369==-- From kwade at redhat.com Thu Jun 4 22:06:03 2015 Content-Type: multipart/mixed; boundary="===============6988529605828185766==" MIME-Version: 1.0 From: Karsten Wade To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Sat, 18 Sep 2004 11:47:47 -0700 Message-ID: <1095533267.4078.5400.camel@erato.phig.org> In-Reply-To: 414C7C44.50501@redhat.com --===============6988529605828185766== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Sat, 2004-09-18 at 11:19, Mark Johnson wrote: > Karsten Wade wrote: > > will get to choose to > > use a parallel XML toolchain based on the FDP tools for the Enterprise > > Linux 4 release ... well, probably nearly exactly the FDP tools with our > > XSL = > = > This is the hope, anyway. FDP certainly provides an excellent test = > case for a given toolchain. > = > However, we may end up with something entirely different, like a = > java-based system. > = > We may, e.g., decide that Saxon is more appropriate as an XSLT = > processor (due to its docbook & other extensions), and that FOP is = > adequate for our FO --> PDF needs, instead of having to revert to = > the tried & true jade/DSSSL combo for PDF output. XSLT and XSL-FO = > are simply easier to deal with than is DSSSL. Well, I was specific about being general ;-) ... perhaps FDP should consider the solution you suggest for the same reasons. There is = synergy that would come out of having the toolchains in alignment. - Karsten -- = Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 --===============6988529605828185766==-- From davep at dpawson.co.uk Thu Jun 4 22:06:04 2015 Content-Type: multipart/mixed; boundary="===============8127740343946489025==" MIME-Version: 1.0 From: Dave Pawson To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Sat, 18 Sep 2004 20:55:11 +0100 Message-ID: <1095537311.3580.5.camel@homer> In-Reply-To: 1095530764.4078.5271.camel@erato.phig.org --===============8127740343946489025== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Sat, 2004-09-18 at 19:06, Karsten Wade wrote: > On Sat, 2004-09-18 at 05:24, Dave Pawson wrote: > = > > What rationale is there for remaining with the SGML toolchain? > = > Ironically, the same reason that businesses worldwide stick with > old-but-working systems, where working =3D=3D we hacked it to work well > enough to ship. > = > For the time to produce Enterprise Linux 4, we didn't have enough cycles > to do the R&D ourselves and start writing our guides for the next > release. There are significant cross-team constraints, such as having > percentages of guides string and code frozen for the translation team to > work on. I gather you're speaking for rhel Karsten? I'm asking about fc2,3. > = > Frankly, it was pretty daunting to imagine doing the XML toolchain all > ourselves. = It was done for you, open src, 5 years ago. > At the time that we had to choose go/no-go on switching to > XML, there were too many problems in the community tools (xmlto PDF > conversion being a big one, iirc), so we had to stick with SGML. Once > we started working in SGML for the production release, we had to stick > with it all the way through until release. I made those decisions in 99. Why has it taken so long for rh to review them? Are they really so 'big blue bound'? > = > That means I'm writing 100% in XML, as soon as I take the few hours to > convert my existing work from SGML. :-) Take a look at James Clarks sx. It works. The XML docbook toolchain started in 98. I see no call for pdf in fc2? So fop shouldn't be a blocker, though its probably more than good enough for our use should pdf be wanted. -- = Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl --===============8127740343946489025==-- From davep at dpawson.co.uk Thu Jun 4 22:06:04 2015 Content-Type: multipart/mixed; boundary="===============8856573037565023329==" MIME-Version: 1.0 From: Dave Pawson To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Sat, 18 Sep 2004 20:58:18 +0100 Message-ID: <1095537498.3580.9.camel@homer> In-Reply-To: 414C7C44.50501@redhat.com --===============8856573037565023329== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Sat, 2004-09-18 at 19:19, Mark Johnson wrote: > = > This is the hope, anyway. FDP certainly provides an excellent test = > case for a given toolchain. > = > However, we may end up with something entirely different, like a = > java-based system. > = > We may, e.g., decide that Saxon is more appropriate as an XSLT = > processor (due to its docbook & other extensions), and that FOP is = > adequate for our FO --> PDF needs, instead of having to revert to = > the tried & true jade/DSSSL combo for PDF output. XSLT and XSL-FO = > are simply easier to deal with than is DSSSL. +1. Which xslt engine is almost immaterial till we move on to xslt 2.0. I've preferred Saxon simply because it appears closer to the 1.0 rec. Apache Xalan is perfectly suited though. > = > At any rate, we won't be committing to any new toolchain (and = > changing all RHEL docs over to XML) until after RHEL4 is released. Which 'we' Mark? = -- = Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl --===============8856573037565023329==-- From mjohnson at redhat.com Thu Jun 4 22:06:04 2015 Content-Type: multipart/mixed; boundary="===============7329717954585620867==" MIME-Version: 1.0 From: Mark Johnson To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Sat, 18 Sep 2004 18:30:37 -0400 Message-ID: <414CB70D.7030209@redhat.com> In-Reply-To: 1095537498.3580.9.camel@homer --===============7329717954585620867== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Dave Pawson wrote: >>At any rate, we won't be committing to any new toolchain (and = >>changing all RHEL docs over to XML) until after RHEL4 is released. > = > = > Which 'we' Mark? Whoops. By 'we" I meant the internal Red Hat docs group, not the = FDP. Sorry if my statement misled anyone. Cheers, Mark -- = ---------------------------------------------------------- Mark Johnson OS Product Documentation Engineering, Red Hat, Inc. Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 --===============7329717954585620867==-- From kwade at redhat.com Thu Jun 4 22:06:04 2015 Content-Type: multipart/mixed; boundary="===============5754824578839011857==" MIME-Version: 1.0 From: Karsten Wade To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Sat, 18 Sep 2004 22:40:06 -0700 Message-ID: <1095572405.4078.7344.camel@erato.phig.org> In-Reply-To: 1095537311.3580.5.camel@homer --===============5754824578839011857== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Sat, 2004-09-18 at 12:55, Dave Pawson wrote: > On Sat, 2004-09-18 at 19:06, Karsten Wade wrote: > > On Sat, 2004-09-18 at 05:24, Dave Pawson wrote: > > = > > > What rationale is there for remaining with the SGML toolchain? > > = > > Ironically, the same reason that businesses worldwide stick with > > old-but-working systems, where working =3D=3D we hacked it to work well > > enough to ship. > > = > > For the time to produce Enterprise Linux 4, we didn't have enough cycles > > to do the R&D ourselves and start writing our guides for the next > > release. There are significant cross-team constraints, such as having > > percentages of guides string and code frozen for the translation team to > > work on. > I gather you're speaking for rhel Karsten? Never let it be said that I speak for RHEL ... :) ... I speak for myself only, unless otherwise stated. > I'm asking about fc2,3. I never would have guessed that. Are you asking, "What rationale is there for Fedora to use the SGML toolchain?"? Because the answer is, what are you talking about?, Fedora is not using the SGML toolchain. > > Frankly, it was pretty daunting to imagine doing the XML toolchain all > > ourselves. = > It was done for you, open src, 5 years ago. [snip] > I made those decisions in 99. Why has it taken so long for rh to review > them? Are they really so 'big blue bound'? I wasn't around during all that time, so I can't speak for decisions made before I was part of the team. My explanation of how a company can get locked into using an aging system because of the difficulty of change should be explanation enough. It is a common enough occurrence. If you don't understand the example, perhaps it's because you haven't experienced it yet? It's far easier for an individual to change systems than for a company. Anyway, the point is no longer moot, since it turns out you were not asking me about RHEL. > > That means I'm writing 100% in XML, as soon as I take the few hours to > > convert my existing work from SGML. :-) > Take a look at James Clarks sx. It works. I will, thanks; that may help with existing SGML guides. Still, we've been trying to follow XML practices, and in many cases we can get away with just changing the DOCTYPE. Most of the work I have to do is around directory structure and Makefiles, I reckon. > I see no call for pdf in fc2? So fop shouldn't be a blocker, > though its probably more than good enough for our use should pdf be > wanted. PDF is wanted. I'm not personally bound to the dead tree method of documenting, but many of our readers are. An Installation Guide, for example, is a wonderful thing to be printed in front of you when you are doing your first Fedora Core install. - Karsten -- = Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 --===============5754824578839011857==-- From davep at dpawson.co.uk Thu Jun 4 22:06:04 2015 Content-Type: multipart/mixed; boundary="===============1375944433608345244==" MIME-Version: 1.0 From: Dave Pawson To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Sun, 19 Sep 2004 08:42:10 +0100 Message-ID: <1095579730.2519.9.camel@homer> In-Reply-To: 1095572405.4078.7344.camel@erato.phig.org --===============1375944433608345244== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Sun, 2004-09-19 at 06:40, Karsten Wade wrote: > > I gather you're speaking for rhel Karsten? > = > Never let it be said that I speak for RHEL ... :) ... I speak for myself > only, unless otherwise stated. In which case my question remains, modified. Are fc documents being processed by 'todays' tools, i.e. xslt and the current docbook stylesheets? > Because the answer is, what are you talking about?, Fedora is not using > the SGML toolchain. You refer to them so regularly Karsten, I'd presumed you were using them? > My explanation of how a company can get locked into using an aging > system because of the difficulty of change should be explanation > enough. It is a common enough occurrence. > = > If you don't understand the example, perhaps it's because you haven't > experienced it yet? It's far easier for an individual to change systems > than for a company. I used DSSSL and SGML for about 12 months, then XML and its tools started to appear. = I have seen what I called the 'blue' effect though. = I find it repugnant, and rarely justifiable in terms of cost. > > > That means I'm writing 100% in XML, as soon as I take the few hours to > > > convert my existing work from SGML. :-) > > Take a look at James Clarks sx. It works. > = > I will, thanks; that may help with existing SGML guides. A while back I moved most of the xfree-86 docs over to XML that way. Its not 100% automated, but it covers the grunt work, and leaves workable documents. > Still, we've > been trying to follow XML practices, and in many cases we can get away > with just changing the DOCTYPE. = sx, with the doctype remaining that of the SGML dtd is mostly cleaner, especially for those making use of the SGML shorthands. Thereafter, a stylesheet can undo most of the remaining issues to produce a valid document. > PDF is wanted. In the fc2 documentation? I haven't seen any. = Is the current fop in use? > = > I'm not personally bound to the dead tree method of documenting, but > many of our readers are. = Fedora readers? -- = Regards DaveP. XSLT&Docbook FAQ http://www.dpawson.co.uk/xsl --===============1375944433608345244==-- From kwade at redhat.com Thu Jun 4 22:06:04 2015 Content-Type: multipart/mixed; boundary="===============7762399970799689644==" MIME-Version: 1.0 From: Karsten Wade To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Mon, 20 Sep 2004 08:06:12 -0700 Message-ID: <1095692771.4078.13297.camel@erato.phig.org> In-Reply-To: 1095579730.2519.9.camel@homer --===============7762399970799689644== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Sun, 2004-09-19 at 00:42, Dave Pawson wrote: > On Sun, 2004-09-19 at 06:40, Karsten Wade wrote: > = > > > I gather you're speaking for rhel Karsten? > > = > > Never let it be said that I speak for RHEL ... :) ... I speak for myself > > only, unless otherwise stated. > = > In which case my question remains, modified. > Are fc documents being processed by 'todays' tools, i.e. xslt > and the current docbook stylesheets? Are you asking me to open up the FDP Makefile for you? Ok ... Fedora documentation is processed using xmlto and a custom XSL that relies upon the standard DB XSL with some modifications (mostly different Booleans, iirc). fedora-docs/xsl/main-{pdf,html}.xsl > > Because the answer is, what are you talking about?, Fedora is not using > > the SGML toolchain. > = > You refer to them so regularly Karsten, I'd presumed you were using > them? I'd have to do an archives search, and I'm not going to :), but I'm pretty sure I usually refer to the SGML toolchain when explaining the history behind a practice that has been carried over to Fedora docs. In other words, people such as you ask why we do something, and in part of explaining that, I give the history. Understanding where you came from is an essential part of understanding where you are today. > > My explanation of how a company can get locked into using an aging > > system because of the difficulty of change should be explanation > > enough. It is a common enough occurrence. > > = > > If you don't understand the example, perhaps it's because you haven't > > experienced it yet? It's far easier for an individual to change systems > > than for a company. > I used DSSSL and SGML for about 12 months, then XML and its tools > started to appear. = > I have seen what I called the 'blue' effect though. = > I find it repugnant, and rarely justifiable in terms of cost. *shrug* Welcome to the real world, Dave. I'd also reckon that in terms of the real world, you are wrong that it is 'rarely' justifiable in terms of cost. I'm not an ROI expert, but I've done a fair number of enterprise assessments, and it's hard to ever know what the exact cost of an existing system. > > PDF is wanted. > In the fc2 documentation? I haven't seen any. = Right, I believe there has been a problem with working conversion to PDF? > Is the current fop in use? No. Again checking in the Makefile, we are using xmlto and a custom XSL. It's not perfect. Hence the discussion to use different tools. > > > I'm not personally bound to the dead tree method of documenting, but > > many of our readers are. = > Fedora readers? Yes. - Karsten -- = Karsten Wade, RHCE, Tech Writer a lemon is just a melon in disguise http://people.redhat.com/kwade/ gpg fingerprint: 2680 DBFD D968 3141 0115 5F1B D992 0E06 AD0E 0C41 --===============7762399970799689644==-- From mjohnson at redhat.com Thu Jun 4 22:06:05 2015 Content-Type: multipart/mixed; boundary="===============2897035718195172531==" MIME-Version: 1.0 From: Mark Johnson To: docs at lists.fedoraproject.org Subject: Re: draft notice text Date: Tue, 21 Sep 2004 10:52:17 -0400 Message-ID: <41504021.1070804@redhat.com> In-Reply-To: 1095692771.4078.13297.camel@erato.phig.org --===============2897035718195172531== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Karsten Wade wrote: > On Sun, 2004-09-19 at 00:42, Dave Pawson wrote: >> Is the current fop in use? > = > = > No. Again checking in the Makefile, we are using xmlto and a custom > XSL. = xmlto is a just bash wrapper script that, for pdf, is using the = passivetex macros, and hence the TeX backend. FWIW, we've[1] done some RH docs testing and found that FOP does a = *much*, much better job than passivetex, esp when it comes to tables. It appears that passivetex is no longer being actively maintained. = (I'll find out about this last point, as I'm currently having a = discussion with the passivetex developer about a completely = different issue.) [when I say we, I actually mean John Ha, the docs team tech lead:] Cheers, Mark -- = ---------------------------------------------------------- Mark Johnson OS Product Documentation Engineering, Red Hat, Inc. Tel: 919.754.4151 Fax: 919.754.3708 GPG fp: DBEA FA3C C46A 70B5 F120 568B 89D5 4F61 C07D E242 --===============2897035718195172531==--