From jfearn at redhat.com Thu Oct 2 05:20:12 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Thu, 02 Oct 2008 15:20:12 +1000 Subject: [publican-list] Use of language-codes in Publican In-Reply-To: <3509869.1991222752337247.JavaMail.asgeirf@localhost.localdomain> References: <3509869.1991222752337247.JavaMail.asgeirf@localhost.localdomain> Message-ID: <48E45A0C.5000005@redhat.com> Asgeir Frimannsson wrote: > ----- "Jeff Fearn" wrote: > >> Asgeir Frimannsson wrote: >>> ----- "Asgeir Frimannsson" wrote: >>>> Hi publicans and others, >>>> >>>> I was doing some work earlier today with Fedora release notes and >>>> publican, and noticed a potential issue with locale names. >>>> >>>> Publican seem to expect locales in the form of $lang-$country, >> e.g. >>>> en-US or hi-IN. >>>> >>>> 1) Many open source projects use underscore rather than hyphen for >>>> locale codes, for example en_US or hi_IN. I'm all in favour of the >>>> publican-approach, and converting projects to use these is >> trivial. >>>> 2) For some languages, a country code in the locale name is not >> used, >>>> and this breaks publican when running 'make report-all'. >>> Sorry, the target that fails is 'publish-report', where the process >> spits out a lot of messages like: >>> "Use of uninitialized value $language in string eq at >> /usr/bin/StSe_Reports line 72." >> >> This is a minor bug in the way this script generates the html reports. >> Are there any other issues? >> >> Does 'make report-total-all' work properly? > > Yes, this seem to work fine. > > I have no idea of how and what the other targets do, but I see heaps of references in the documentation to '-' (via make help), and using a code without the '-' would IMO not typically produce a predictable result :) > I'm not going to change the language about - since that's the "recommended" way, but it should certainly work just using . I opened this bug: https://bugzilla.redhat.com/show_bug.cgi?id=465201 And closed it :) I'm pretty sure two character language codes should work correctly now. I've certainly been able to update translations using two character codes, produce HTML, PDF and RPM outputs, and translation reports. I also reworked the layout of the reports since I thought they looked awful. You can see the new layout at http://jfearn.fedorapeople.org/Test_Report/ Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From bugzilla at redhat.com Fri Oct 3 06:54:03 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 3 Oct 2008 02:54:03 -0400 Subject: [publican-list] [Bug 465411] PDF build adds "1" characters into URLs, causing links to fail if people highlight and copy In-Reply-To: References: Message-ID: <200810030654.m936s3Dk029096@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=465411 --- Comment #1 from Murray McAllister 2008-10-03 02:54:03 EDT --- Issue occurs in publican-fedora-0.15-0.el5 and publican-redhat-0.15-0.el5. I have not tried anything else. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Fri Oct 3 06:50:59 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 3 Oct 2008 02:50:59 -0400 Subject: [publican-list] [Bug 465411] New: PDF build adds "1" characters into URLs, causing links to fail if people highlight and copy Message-ID: Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. Summary: PDF build adds "1" characters into URLs, causing links to fail if people highlight and copy https://bugzilla.redhat.com/show_bug.cgi?id=465411 Summary: PDF build adds "1" characters into URLs, causing links to fail if people highlight and copy Product: Red Hat Enterprise Linux 5 Version: 5.2 Platform: All OS/Version: Linux Status: NEW Severity: medium Priority: medium Component: publican AssignedTo: jfearn at redhat.com ReportedBy: mmcallis at redhat.com QAContact: ecs-dev-list at redhat.com CC: publican-list at redhat.com Classification: Red Hat Created an attachment (id=319323) --> (https://bugzilla.redhat.com/attachment.cgi?id=319323) "1" characters in links (PDF output) Version-Release number of selected component (if applicable): * Red Hat Enterprise Linux Client release 5.2 (Tikanga) * publican-0.37-0.el5 * fop-0.95-0.2.beta1.rh1.el5 * saxon-6.5.5-1jpp.3.el5 * evince-0.6.0-8.el5 How reproducible: Always, when using "svn co http://svn.fedorahosted.org/svn/selinuxguide" Steps to Reproduce: 1. svn co http://svn.fedorahosted.org/svn/selinuxguide 2. cd selinuxguide/community/trunk/SELinux_User_Guide 3. make pdf-en-US 4. See page 4 Actual results: * "1" characters inserted into links (see attached). * clicking on the link takes you to the correct page (no "1" characters in the link). * right-click, copy link, also takes you to the correct page (no "1" characters in the link). Highlighting the link, and then copying, copies the "1" characters, causing the link to fail. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Sat Oct 4 04:55:06 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Sat, 4 Oct 2008 00:55:06 -0400 Subject: [publican-list] [Bug 462206] RFE: please support "check" and "cross" characters in PDF In-Reply-To: References: Message-ID: <200810040455.m944t684014809@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=462206 --- Comment #1 from Murray McAllister 2008-10-04 00:55:05 EDT --- Hi, Any updates on whether this is possible, and if it is, when to expect check and cross to be supported in PDF? Thanks! -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Sun Oct 5 23:16:01 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Sun, 5 Oct 2008 19:16:01 -0400 Subject: [publican-list] [Bug 465411] PDF build adds "1" characters into URLs, causing links to fail if people highlight and copy In-Reply-To: References: Message-ID: <200810052316.m95NG1ao010832@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=465411 --- Comment #2 from Jeff Fearn 2008-10-05 19:16:00 EDT --- There is a bug in the way the URL is being escaped. It may take me some time to get to this as I am working on another system atm. You can work around this bug by copying the URL in to the tag body. e.g. http://www.gentoo.org/proj/en/hardened/selinux/selinux-handbook.xml or Gentoo SELinux Handbook This bug may have existed for sometime since, in my experience, very few people leave the ulink body empty. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Mon Oct 6 05:49:29 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Mon, 6 Oct 2008 01:49:29 -0400 Subject: [publican-list] [Bug 462205] RFE: make test and html, no errors when number of cells is more than the specified value In-Reply-To: References: Message-ID: <200810060549.m965nTQx018376@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=462205 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |CLOSED Fixed In Version| |0.38 Resolution| |CURRENTRELEASE --- Comment #3 from Jeff Fearn 2008-10-06 01:49:28 EDT --- Added check to compare cols to the number of entry tags per row and report any tables that fail this check. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Mon Oct 6 06:17:38 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Mon, 6 Oct 2008 02:17:38 -0400 Subject: [publican-list] [Bug 462206] RFE: please support "check" and "cross" characters in PDF In-Reply-To: References: Message-ID: <200810060617.m966HcUK024722@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=462206 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |ASSIGNED --- Comment #2 from Jeff Fearn 2008-10-06 02:17:37 EDT --- The check and cross entities are not in the liberation fonts. Since FOP can not do per glyph font selection the PDF can not fall back to another font like the HTML renderers can. It may be possible to use a tag or attribute specifically to override the font used, however this would be messy so you'd need to get some community consensus on how that would be done. It may be easier to get the liberation maintainers to add these glyphs to the font :) -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Tue Oct 7 03:57:02 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Mon, 6 Oct 2008 23:57:02 -0400 Subject: [publican-list] [Bug 462991] Increase space before Glossary and Appendix entries in TOC In-Reply-To: References: Message-ID: <200810070357.m973v2IB005585@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=462991 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |CLOSED Fixed In Version| |0.38 Resolution| |CURRENTRELEASE --- Comment #1 from Jeff Fearn 2008-10-06 23:57:01 EDT --- Gave glossary and appendix in TOC same style as chapter. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Tue Oct 7 04:03:36 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 00:03:36 -0400 Subject: [publican-list] [Bug 462552] syntax highlighting xml comments difficult to read In-Reply-To: References: Message-ID: <200810070403.m9743a0e006646@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=462552 --- Comment #2 from Jeff Fearn 2008-10-07 00:03:35 EDT --- Made comments more visible. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Tue Oct 7 04:03:06 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 00:03:06 -0400 Subject: [publican-list] [Bug 462552] syntax highlighting xml comments difficult to read In-Reply-To: References: Message-ID: <200810070403.m97436K5006878@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=462552 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |CLOSED Fixed In Version| |0.38 Resolution| |CURRENTRELEASE -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 8 01:07:35 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 21:07:35 -0400 Subject: [publican-list] [Bug 466067] New: Remove stated methodolgy for writing procedures from Typographic Conventions Message-ID: Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. Summary: Remove stated methodolgy for writing procedures from Typographic Conventions https://bugzilla.redhat.com/show_bug.cgi?id=466067 Summary: Remove stated methodolgy for writing procedures from Typographic Conventions Product: Red Hat Enterprise Linux 5 Version: 5.2 Platform: All OS/Version: Linux Status: NEW Severity: medium Priority: medium Component: publican AssignedTo: jfearn at redhat.com ReportedBy: daobrien at redhat.com QAContact: ecs-dev-list at redhat.com CC: publican-list at redhat.com Classification: Red Hat Description of problem: Our Typo. Conventions state that we use "the > shorthand (used) to indicate traversal through a menu and its sub-menus." I have yet to see an instance of this. Instead, the "Click this to display that and then select something" is far more prevalent and the normal approach that I use. I'm not arguing for one approach or the other, but until we choose and _implement_ a standard, we should not state that we use one. Version-Release number of selected component (if applicable): publican-0.37-0.el5 How reproducible: Steps to Reproduce: 1. 2. 3. Actual results: Expected results: Additional info: -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 8 01:16:33 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 21:16:33 -0400 Subject: [publican-list] [Bug 464038] RFE: please support citerefentry, refentrytitle, and manvolnum In-Reply-To: References: Message-ID: <200810080116.m981GX4h002380@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=464038 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |CLOSED Fixed In Version| |0.38 Resolution| |CURRENTRELEASE --- Comment #1 from Jeff Fearn 2008-10-07 21:16:32 EDT --- Added citerefentry, refentrytitle, and manvolnum to list of QA'd tags. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 8 01:25:00 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 21:25:00 -0400 Subject: [publican-list] [Bug 461708] unsupported "developer content relevant" tags In-Reply-To: References: Message-ID: <200810080125.m981P09f004315@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461708 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Flag| |needinfo?(dmison at redhat.com | |) --- Comment #1 from Jeff Fearn 2008-10-07 21:24:59 EDT --- Do these tags render correctly in html, html-single and PDF? Do the html-single and html outputs pass validation for XHTML 1.0 strict at http://validator.w3.org ? -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 8 01:25:59 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 21:25:59 -0400 Subject: [publican-list] [Bug 461870] Update list of known tags In-Reply-To: References: Message-ID: <200810080125.m981PxVE004949@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461870 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Flag|needinfo?(daobrien at redhat.c |needinfo+ |om) | -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 8 01:25:38 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 21:25:38 -0400 Subject: [publican-list] [Bug 461708] unsupported "developer content relevant" tags In-Reply-To: References: Message-ID: <200810080125.m981Pcs9004866@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461708 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Flag|needinfo?(dmison at redhat.com |needinfo+ |) | -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 8 01:25:13 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 21:25:13 -0400 Subject: [publican-list] [Bug 461870] Update list of known tags In-Reply-To: References: Message-ID: <200810080125.m981PDXE004741@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461870 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Flag| |needinfo?(daobrien at redhat.c | |om) --- Comment #1 from Jeff Fearn 2008-10-07 21:25:12 EDT --- Do these tags render correctly in html, html-single and PDF? Do the html-single and html outputs pass validation for XHTML 1.0 strict at http://validator.w3.org ? -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 8 01:25:06 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 21:25:06 -0400 Subject: [publican-list] [Bug 461864] Add and to list of "known tags" In-Reply-To: References: Message-ID: <200810080125.m981P618004699@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461864 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Flag| |needinfo?(daobrien at redhat.c | |om) --- Comment #1 from Jeff Fearn 2008-10-07 21:25:05 EDT --- Do these tags render correctly in html, html-single and PDF? Do the html-single and html outputs pass validation for XHTML 1.0 strict at http://validator.w3.org ? -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 8 01:25:50 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 21:25:50 -0400 Subject: [publican-list] [Bug 461864] Add and to list of "known tags" In-Reply-To: References: Message-ID: <200810080125.m981Po99004901@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461864 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Flag|needinfo?(daobrien at redhat.c |needinfo+ |om) | -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 8 01:33:19 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 21:33:19 -0400 Subject: [publican-list] [Bug 461708] unsupported "developer content relevant" tags In-Reply-To: References: Message-ID: <200810080133.m981XJMH006721@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461708 --- Comment #2 from Darrin Mison 2008-10-07 21:33:18 EDT --- They just render as normal text, no special formatting. The upstream source for a couple of my books have a lot of these tags as they are developer guides, and it produces *a lot* of warnings. It's not a big-deal, but *some* formatting for those would be nice. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 8 01:41:33 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 21:41:33 -0400 Subject: [publican-list] [Bug 466067] Remove stated methodolgy for writing procedures from Typographic Conventions In-Reply-To: References: Message-ID: <200810080141.m981fXJW008762@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=466067 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |ASSIGNED AssignedTo|jfearn at redhat.com |bforte at redhat.com -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 8 01:47:14 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 7 Oct 2008 21:47:14 -0400 Subject: [publican-list] [Bug 461708] unsupported "developer content relevant" tags In-Reply-To: References: Message-ID: <200810080147.m981lEih010346@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461708 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |bforte at redhat.com --- Comment #3 from Jeff Fearn 2008-10-07 21:47:13 EDT --- Darrin, do the html-single and html outputs pass validation for XHTML 1.0 strict at http://validator.w3.org ? Brian, should these tags be mono-spaced bold or proportional bold? -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 8 05:21:58 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Wed, 8 Oct 2008 01:21:58 -0400 Subject: [publican-list] [Bug 465411] PDF build adds "1" characters into URLs, causing links to fail if people highlight and copy In-Reply-To: References: Message-ID: <200810080521.m985LwvX027297@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=465411 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |CLOSED Fixed In Version| |0.38 Resolution| |CURRENTRELEASE --- Comment #3 from Jeff Fearn 2008-10-08 01:21:57 EDT --- Disabled ulink.hyphenate xsl variable, it was being set to 1. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From mmcgrath at redhat.com Thu Oct 9 16:17:50 2008 From: mmcgrath at redhat.com (Mike McGrath) Date: Thu, 9 Oct 2008 11:17:50 -0500 (CDT) Subject: [publican-list] Organization issue and multiple docs Message-ID: I'm working on what will ultimately be a rather large amount of docs. At present I've got a set. The set has a bunch of books by topic and the books have a bunch of chapters, sometimes by audience (sysadmins, managers, end users) I'm not quite happy with how it's turned out and trying to decide whether to organize by audience, or by topic has been difficult. I was wondering if publican can make multiple docs at once. This would allow me to have the one monolithic set I have now, but also smaller sets that contain just sections relevant to the audience. -Mike From mmcgrath at redhat.com Thu Oct 9 16:25:04 2008 From: mmcgrath at redhat.com (Mike McGrath) Date: Thu, 9 Oct 2008 11:25:04 -0500 (CDT) Subject: [publican-list] Migration docs Message-ID: Where can I find how to best migrate from publican-0.33-0 to 0.37-0? I'm getting errors I don't quite understand like: END: xml-en-US Thu Oct 9 11:21:33 CDT 2008 START: test-en-US Thu Oct 9 11:21:33 CDT 2008 warning: failed to load external entity "tmp/en-US/xml/Community_Services_Infrastructure_Standards.xml" make: *** [test-en-US] Error 1 I don't have any actual xml files called that nor do I reference xml files with that name. -Mike From stickster at gmail.com Thu Oct 9 16:28:56 2008 From: stickster at gmail.com (Paul W. Frields) Date: Thu, 09 Oct 2008 16:28:56 +0000 Subject: [publican-list] Organization issue and multiple docs In-Reply-To: References: Message-ID: <1223569736.26136.3.camel@localhost.localdomain> On Thu, 2008-10-09 at 11:17 -0500, Mike McGrath wrote: > I'm working on what will ultimately be a rather large amount of docs. At > present I've got a set. The set has a bunch of books by topic and the > books have a bunch of chapters, sometimes by audience (sysadmins, > managers, end users) > > I'm not quite happy with how it's turned out and trying to decide whether > to organize by audience, or by topic has been difficult. I was wondering > if publican can make multiple docs at once. This would allow me to have > the one monolithic set I have now, but also smaller sets that contain just > sections relevant to the audience. DocBook is capable of handling a @role attribute, like: That @role attribute is sometimes called (IIRC) "document profiling," and there's information about it in the XSLT Handbook and the DocBook guide, I think. I'm certain that RH Docs has used this for works like the Installation Guide where a specific procedure changes depending on, say, the architecture on which you're installing RHEL. -- Paul W. Frields gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 http://paul.frields.org/ - - http://pfrields.fedorapeople.org/ irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From mmcgrath at redhat.com Thu Oct 9 16:40:41 2008 From: mmcgrath at redhat.com (Mike McGrath) Date: Thu, 9 Oct 2008 11:40:41 -0500 (CDT) Subject: [publican-list] Organization issue and multiple docs In-Reply-To: <1223569736.26136.3.camel@localhost.localdomain> References: <1223569736.26136.3.camel@localhost.localdomain> Message-ID: On Thu, 9 Oct 2008, Paul W. Frields wrote: > On Thu, 2008-10-09 at 11:17 -0500, Mike McGrath wrote: > > I'm working on what will ultimately be a rather large amount of docs. At > > present I've got a set. The set has a bunch of books by topic and the > > books have a bunch of chapters, sometimes by audience (sysadmins, > > managers, end users) > > > > I'm not quite happy with how it's turned out and trying to decide whether > > to organize by audience, or by topic has been difficult. I was wondering > > if publican can make multiple docs at once. This would allow me to have > > the one monolithic set I have now, but also smaller sets that contain just > > sections relevant to the audience. > > DocBook is capable of handling a @role attribute, like: > > > > > > > > > > > That @role attribute is sometimes called (IIRC) "document profiling," > and there's information about it in the XSLT Handbook and the DocBook > guide, I think. > > I'm certain that RH Docs has used this for works like the Installation > Guide where a specific procedure changes depending on, say, the > architecture on which you're installing RHEL. > Ok, thats freaking awesome. Is there a way to build a book where "role==users" ? -Mike From jaredsmith at jaredsmith.net Thu Oct 9 16:46:57 2008 From: jaredsmith at jaredsmith.net (Jared Smith) Date: Thu, 09 Oct 2008 12:46:57 -0400 Subject: [publican-list] Organization issue and multiple docs In-Reply-To: References: <1223569736.26136.3.camel@localhost.localdomain> Message-ID: <1223570817.19380.4.camel@localhost.localdomain> On Thu, 2008-10-09 at 11:40 -0500, Mike McGrath wrote: > Ok, thats freaking awesome. Is there a way to build a book where > "role==users" ? Absolutely... I'm not sure what the proper way to do this in Publican is, but my own toolchains have always just had a setting in the Makefile that generates the document based on a particular role. If you're using xsltproc to process your XML, you can simply set "--stringparam profile.condition users" to have it only process nodes that have no role set or the role == users. -Jared From stickster at gmail.com Thu Oct 9 17:02:38 2008 From: stickster at gmail.com (Paul W. Frields) Date: Thu, 09 Oct 2008 17:02:38 +0000 Subject: [publican-list] Organization issue and multiple docs In-Reply-To: <1223570817.19380.4.camel@localhost.localdomain> References: <1223569736.26136.3.camel@localhost.localdomain> <1223570817.19380.4.camel@localhost.localdomain> Message-ID: <1223571758.26136.18.camel@localhost.localdomain> On Thu, 2008-10-09 at 12:46 -0400, Jared Smith wrote: > On Thu, 2008-10-09 at 11:40 -0500, Mike McGrath wrote: > > Ok, thats freaking awesome. Is there a way to build a book where > > "role==users" ? > > Absolutely... I'm not sure what the proper way to do this in Publican > is, but my own toolchains have always just had a setting in the Makefile > that generates the document based on a particular role. If you're using > xsltproc to process your XML, you can simply set "--stringparam > profile.condition users" to have it only process nodes that have no role > set or the role == users. Jared makes a great point I stupidly left out, which is that by leaving the @role out entirely, you more-or-less guarantee that an XML element will be in all the versions of the document. You only need to put the @role in where it's needed. -- Paul W. Frields gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 http://paul.frields.org/ - - http://pfrields.fedorapeople.org/ irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From mmcgrath at redhat.com Thu Oct 9 20:57:42 2008 From: mmcgrath at redhat.com (Mike McGrath) Date: Thu, 9 Oct 2008 15:57:42 -0500 (CDT) Subject: [publican-list] Organization issue and multiple docs In-Reply-To: <1223571758.26136.18.camel@localhost.localdomain> References: <1223569736.26136.3.camel@localhost.localdomain> <1223570817.19380.4.camel@localhost.localdomain> <1223571758.26136.18.camel@localhost.localdomain> Message-ID: On Thu, 9 Oct 2008, Paul W. Frields wrote: > On Thu, 2008-10-09 at 12:46 -0400, Jared Smith wrote: > > On Thu, 2008-10-09 at 11:40 -0500, Mike McGrath wrote: > > > Ok, thats freaking awesome. Is there a way to build a book where > > > "role==users" ? > > > > Absolutely... I'm not sure what the proper way to do this in Publican > > is, but my own toolchains have always just had a setting in the Makefile > > that generates the document based on a particular role. If you're using > > xsltproc to process your XML, you can simply set "--stringparam > > profile.condition users" to have it only process nodes that have no role > > set or the role == users. > > Jared makes a great point I stupidly left out, which is that by leaving > the @role out entirely, you more-or-less guarantee that an XML element > will be in all the versions of the document. You only need to put the > @role in where it's needed. > yeah, I think this is exactly what I want, now I just have to figure out how to get it to work with publican. -Mike From bugzilla at redhat.com Thu Oct 9 21:44:24 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 9 Oct 2008 17:44:24 -0400 Subject: [publican-list] [Bug 465411] PDF build adds "1" characters into URLs, causing links to fail if people highlight and copy In-Reply-To: References: Message-ID: <200810092144.m99LiOIL007070@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=465411 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |kanarip at kanarip.com --- Comment #4 from Jeff Fearn 2008-10-09 17:44:23 EDT --- *** Bug 466308 has been marked as a duplicate of this bug. *** -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From mhideo at redhat.com Thu Oct 9 22:03:01 2008 From: mhideo at redhat.com (Michael Hideo-Smith) Date: Thu, 9 Oct 2008 18:03:01 -0400 (EDT) Subject: [publican-list] Migration docs In-Reply-To: Message-ID: <1068030437.2029001223589781465.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> ----- "Mike McGrath" wrote: > From: "Mike McGrath" > To: publican-list at redhat.com > Sent: Friday, October 10, 2008 2:25:04 AM GMT +10:00 Brisbane > Subject: [publican-list] Migration docs > > Where can I find how to best migrate from publican-0.33-0 to 0.37-0? > I'm > getting errors I don't quite understand like: > > END: xml-en-US Thu Oct 9 11:21:33 CDT 2008 > START: test-en-US Thu Oct 9 11:21:33 CDT 2008 > warning: failed to load external entity > "tmp/en-US/xml/Community_Services_Infrastructure_Standards.xml" > make: *** [test-en-US] Error 1 > > > I don't have any actual xml files called that nor do I reference xml > files with that name. > I have put the migration process here: https://fedorahosted.org/publican/wiki/ReleaseNoteVer35 If you run into docbook/publiccan challenges, please seek me out in #publican and i'll do my best to help out. - Mike From jfearn at redhat.com Thu Oct 9 22:03:10 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Fri, 10 Oct 2008 08:03:10 +1000 Subject: [publican-list] Organization issue and multiple docs In-Reply-To: References: <1223569736.26136.3.camel@localhost.localdomain> <1223570817.19380.4.camel@localhost.localdomain> <1223571758.26136.18.camel@localhost.localdomain> Message-ID: <48EE7F9E.8030705@redhat.com> Mike McGrath wrote: > On Thu, 9 Oct 2008, Paul W. Frields wrote: > >> On Thu, 2008-10-09 at 12:46 -0400, Jared Smith wrote: >>> On Thu, 2008-10-09 at 11:40 -0500, Mike McGrath wrote: >>>> Ok, thats freaking awesome. Is there a way to build a book where >>>> "role==users" ? >>> Absolutely... I'm not sure what the proper way to do this in Publican >>> is, but my own toolchains have always just had a setting in the Makefile >>> that generates the document based on a particular role. If you're using >>> xsltproc to process your XML, you can simply set "--stringparam >>> profile.condition users" to have it only process nodes that have no role >>> set or the role == users. >> Jared makes a great point I stupidly left out, which is that by leaving >> the @role out entirely, you more-or-less guarantee that an XML element >> will be in all the versions of the document. You only need to put the >> @role in where it's needed. >> > > yeah, I think this is exactly what I want, now I just have to figure out > how to get it to work with publican. > Hi Mike, publican does not use the role attribute for profiling docbook. This is because some tags use the role attribute for controlling styling of output instead of profiling. e.g. In the default DocBook XSL the para tag uses role to set the css class in XHTML. Publican uses the condition attribute for profiling as this is exclusively used this way and avoids confusion as to what the usage of role means for any particular use. Say you have three conditions, admin, dev, user: For admins For admins and devs make CONDITION=admin html-en-US You can also hard code CONDITION in your Makefile. Building conditional desktop rpms is not currently supported as there is no way to differentiate the rpms. I do believe Don owes me some user documentation on this feature ... pokety poke! Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From stickster at gmail.com Thu Oct 9 23:13:38 2008 From: stickster at gmail.com (Paul W. Frields) Date: Thu, 09 Oct 2008 23:13:38 +0000 Subject: [publican-list] Organization issue and multiple docs In-Reply-To: <48EE7F9E.8030705@redhat.com> References: <1223569736.26136.3.camel@localhost.localdomain> <1223570817.19380.4.camel@localhost.localdomain> <1223571758.26136.18.camel@localhost.localdomain> <48EE7F9E.8030705@redhat.com> Message-ID: <1223594018.26136.84.camel@localhost.localdomain> On Fri, 2008-10-10 at 08:03 +1000, Jeff Fearn wrote: > Mike McGrath wrote: > > On Thu, 9 Oct 2008, Paul W. Frields wrote: > > > >> On Thu, 2008-10-09 at 12:46 -0400, Jared Smith wrote: > >>> On Thu, 2008-10-09 at 11:40 -0500, Mike McGrath wrote: > >>>> Ok, thats freaking awesome. Is there a way to build a book where > >>>> "role==users" ? > >>> Absolutely... I'm not sure what the proper way to do this in Publican > >>> is, but my own toolchains have always just had a setting in the Makefile > >>> that generates the document based on a particular role. If you're using > >>> xsltproc to process your XML, you can simply set "--stringparam > >>> profile.condition users" to have it only process nodes that have no role > >>> set or the role == users. > >> Jared makes a great point I stupidly left out, which is that by leaving > >> the @role out entirely, you more-or-less guarantee that an XML element > >> will be in all the versions of the document. You only need to put the > >> @role in where it's needed. > >> > > > > yeah, I think this is exactly what I want, now I just have to figure out > > how to get it to work with publican. > > > > Hi Mike, publican does not use the role attribute for profiling > docbook. This is because some tags use the role attribute for > controlling styling of output instead of profiling. > > e.g. In the default DocBook XSL the para tag uses role to set the css > class in XHTML. > > Publican uses the condition attribute for profiling as this is > exclusively used this way and avoids confusion as to what the usage of > role means for any particular use. > > Say you have three conditions, admin, dev, user: > > For admins > > For admins and devs > > make CONDITION=admin html-en-US > > You can also hard code CONDITION in your Makefile. > > Building conditional desktop rpms is not currently supported as there > is no way to differentiate the rpms. > > I do believe Don owes me some user documentation on this feature ... > pokety poke! Good stuff Jeff. I should have realized that, given that I use W. for my middle initial in e.g. . -- Paul W. Frields gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 http://paul.frields.org/ - - http://pfrields.fedorapeople.org/ irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From ddomingo at redhat.com Fri Oct 10 03:35:50 2008 From: ddomingo at redhat.com (Don Domingo) Date: Fri, 10 Oct 2008 13:35:50 +1000 Subject: [publican-list] Organization issue and multiple docs In-Reply-To: <48EE7F9E.8030705@redhat.com> References: <1223569736.26136.3.camel@localhost.localdomain> <1223570817.19380.4.camel@localhost.localdomain> <1223571758.26136.18.camel@localhost.localdomain> <48EE7F9E.8030705@redhat.com> Message-ID: <48EECD96.1060103@redhat.com> thanks for the reminder Jeff. i've already made the necessary additions to the Users Guide for a "Conditional Tagging" section, and i asked Murray to commit them since i dont have write access yet. Jeff Fearn wrote: > Mike McGrath wrote: >> On Thu, 9 Oct 2008, Paul W. Frields wrote: >> >>> On Thu, 2008-10-09 at 12:46 -0400, Jared Smith wrote: >>>> On Thu, 2008-10-09 at 11:40 -0500, Mike McGrath wrote: >>>>> Ok, thats freaking awesome. Is there a way to build a book where >>>>> "role==users" ? >>>> Absolutely... I'm not sure what the proper way to do this in Publican >>>> is, but my own toolchains have always just had a setting in the >>>> Makefile >>>> that generates the document based on a particular role. If you're >>>> using >>>> xsltproc to process your XML, you can simply set "--stringparam >>>> profile.condition users" to have it only process nodes that have no >>>> role >>>> set or the role == users. >>> Jared makes a great point I stupidly left out, which is that by leaving >>> the @role out entirely, you more-or-less guarantee that an XML element >>> will be in all the versions of the document. You only need to put the >>> @role in where it's needed. >>> >> >> yeah, I think this is exactly what I want, now I just have to figure out >> how to get it to work with publican. >> > > Hi Mike, publican does not use the role attribute for profiling > docbook. This is because some tags use the role attribute for > controlling styling of output instead of profiling. > > e.g. In the default DocBook XSL the para tag uses role to set the css > class in XHTML. > > Publican uses the condition attribute for profiling as this is > exclusively used this way and avoids confusion as to what the usage of > role means for any particular use. > > Say you have three conditions, admin, dev, user: > > For admins > > For admins and devs > > make CONDITION=admin html-en-US > > You can also hard code CONDITION in your Makefile. > > Building conditional desktop rpms is not currently supported as there > is no way to differentiate the rpms. > > I do believe Don owes me some user documentation on this feature ... > pokety poke! > > Cheers, Jeff. > -------------- next part -------------- A non-text attachment was scrubbed... Name: ddomingo.vcf Type: text/x-vcard Size: 318 bytes Desc: not available URL: From mmcallis at redhat.com Fri Oct 10 04:13:27 2008 From: mmcallis at redhat.com (Murray McAllister) Date: Fri, 10 Oct 2008 14:13:27 +1000 Subject: [publican-list] Organization issue and multiple docs In-Reply-To: <48EECD96.1060103@redhat.com> References: <1223569736.26136.3.camel@localhost.localdomain> <1223570817.19380.4.camel@localhost.localdomain> <1223571758.26136.18.camel@localhost.localdomain> <48EE7F9E.8030705@redhat.com> <48EECD96.1060103@redhat.com> Message-ID: <48EED667.8000805@redhat.com> Don Domingo wrote: > thanks for the reminder Jeff. i've already made the necessary additions > to the Users Guide for a "Conditional Tagging" section, and i asked > Murray to commit them since i dont have write access yet. > I committed your changes to svn. > Jeff Fearn wrote: >> Mike McGrath wrote: >>> On Thu, 9 Oct 2008, Paul W. Frields wrote: >>> >>>> On Thu, 2008-10-09 at 12:46 -0400, Jared Smith wrote: >>>>> On Thu, 2008-10-09 at 11:40 -0500, Mike McGrath wrote: >>>>>> Ok, thats freaking awesome. Is there a way to build a book where >>>>>> "role==users" ? >>>>> Absolutely... I'm not sure what the proper way to do this in Publican >>>>> is, but my own toolchains have always just had a setting in the >>>>> Makefile >>>>> that generates the document based on a particular role. If you're >>>>> using >>>>> xsltproc to process your XML, you can simply set "--stringparam >>>>> profile.condition users" to have it only process nodes that have no >>>>> role >>>>> set or the role == users. >>>> Jared makes a great point I stupidly left out, which is that by leaving >>>> the @role out entirely, you more-or-less guarantee that an XML element >>>> will be in all the versions of the document. You only need to put the >>>> @role in where it's needed. >>>> >>> >>> yeah, I think this is exactly what I want, now I just have to figure out >>> how to get it to work with publican. >>> >> >> Hi Mike, publican does not use the role attribute for profiling >> docbook. This is because some tags use the role attribute for >> controlling styling of output instead of profiling. >> >> e.g. In the default DocBook XSL the para tag uses role to set the css >> class in XHTML. >> >> Publican uses the condition attribute for profiling as this is >> exclusively used this way and avoids confusion as to what the usage of >> role means for any particular use. >> >> Say you have three conditions, admin, dev, user: >> >> For admins >> >> For admins and devs >> >> make CONDITION=admin html-en-US >> >> You can also hard code CONDITION in your Makefile. >> >> Building conditional desktop rpms is not currently supported as there >> is no way to differentiate the rpms. >> >> I do believe Don owes me some user documentation on this feature ... >> pokety poke! >> >> Cheers, Jeff. >> > > _______________________________________________ > publican-list mailing list > publican-list at redhat.com > https://www.redhat.com/mailman/listinfo/publican-list > Wiki: https://fedorahosted.org/publican From jfearn at redhat.com Fri Oct 10 06:05:28 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Fri, 10 Oct 2008 16:05:28 +1000 Subject: [publican-list] Organization issue and multiple docs In-Reply-To: <48EED667.8000805@redhat.com> References: <1223569736.26136.3.camel@localhost.localdomain> <1223570817.19380.4.camel@localhost.localdomain> <1223571758.26136.18.camel@localhost.localdomain> <48EE7F9E.8030705@redhat.com> <48EECD96.1060103@redhat.com> <48EED667.8000805@redhat.com> Message-ID: <48EEF0A8.4060808@redhat.com> Murray McAllister wrote: > Don Domingo wrote: >> thanks for the reminder Jeff. i've already made the necessary >> additions to the Users Guide for a "Conditional Tagging" section, and >> i asked Murray to commit them since i dont have write access yet. >> > I committed your changes to svn. Cool, thanks guys :) Cheers, Jeff. P.S. I will probably release 0.38 next week. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From bugzilla at redhat.com Sun Oct 12 23:50:03 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Sun, 12 Oct 2008 19:50:03 -0400 Subject: [publican-list] [Bug 461708] unsupported "developer content relevant" tags In-Reply-To: References: Message-ID: <200810122350.m9CNo3IB026634@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461708 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |ASSIGNED -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Sun Oct 12 23:50:16 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Sun, 12 Oct 2008 19:50:16 -0400 Subject: [publican-list] [Bug 461870] Update list of known tags In-Reply-To: References: Message-ID: <200810122350.m9CNoGJ7026260@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461870 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |ASSIGNED -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Sun Oct 12 23:50:09 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Sun, 12 Oct 2008 19:50:09 -0400 Subject: [publican-list] [Bug 461864] Add and to list of "known tags" In-Reply-To: References: Message-ID: <200810122350.m9CNo98n026226@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461864 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |ASSIGNED -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Sun Oct 12 23:51:51 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Sun, 12 Oct 2008 19:51:51 -0400 Subject: [publican-list] [Bug 462206] RFE: please support "check" and "cross" characters in PDF In-Reply-To: References: Message-ID: <200810122351.m9CNppvQ027039@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=462206 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|ASSIGNED |CLOSED Resolution| |WONTFIX --- Comment #3 from Jeff Fearn 2008-10-12 19:51:50 EDT --- This is not a bug in publican and should be fixed in either the font or FOP. Please open a bug against either of those components if you feel it's required. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From mmcgrath at redhat.com Tue Oct 14 20:03:58 2008 From: mmcgrath at redhat.com (Mike McGrath) Date: Tue, 14 Oct 2008 15:03:58 -0500 (CDT) Subject: [publican-list] Migration docs In-Reply-To: <1068030437.2029001223589781465.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> References: <1068030437.2029001223589781465.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> Message-ID: On Thu, 9 Oct 2008, Michael Hideo-Smith wrote: > > > > I don't have any actual xml files called that nor do I reference xml > > files with that name. > > > > I have put the migration process here: > https://fedorahosted.org/publican/wiki/ReleaseNoteVer35 > > If you run into docbook/publiccan challenges, please seek me out in #publican and i'll do my best to help out. > Ok, migrations all did what I'd hoped but I am still seeing a "failed to load external entity" issue. To reproduce: git clone git://git.fedorahosted.org/git/csi.git/ make txt-all -Mike From mmcgrath at redhat.com Tue Oct 14 20:13:56 2008 From: mmcgrath at redhat.com (Mike McGrath) Date: Tue, 14 Oct 2008 15:13:56 -0500 (CDT) Subject: [publican-list] Migration docs In-Reply-To: References: <1068030437.2029001223589781465.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> Message-ID: On Tue, 14 Oct 2008, Mike McGrath wrote: > On Thu, 9 Oct 2008, Michael Hideo-Smith wrote: > > > > > > I don't have any actual xml files called that nor do I reference xml > > > files with that name. > > > > > > > I have put the migration process here: > > https://fedorahosted.org/publican/wiki/ReleaseNoteVer35 > > > > If you run into docbook/publiccan challenges, please seek me out in #publican and i'll do my best to help out. > > > > Ok, migrations all did what I'd hoped but I am still seeing a "failed to > load external entity" issue. To reproduce: > > git clone git://git.fedorahosted.org/git/csi.git/ > make txt-all > > Ok, I'm closer now, I was misunderstanding one of the notes on the upgrade page. now I just have a bunch of validity errors that I didn't have before but this is probably related to an F-8 -> F-9 upgrade I recently did on this host. Looking now. -Mike From jfearn at redhat.com Tue Oct 14 22:06:02 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Wed, 15 Oct 2008 08:06:02 +1000 Subject: [publican-list] Migration docs In-Reply-To: References: <1068030437.2029001223589781465.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> Message-ID: <48F517CA.30309@redhat.com> Mike McGrath wrote: > On Thu, 9 Oct 2008, Michael Hideo-Smith wrote: >>> I don't have any actual xml files called that nor do I reference xml >>> files with that name. >>> >> I have put the migration process here: >> https://fedorahosted.org/publican/wiki/ReleaseNoteVer35 >> >> If you run into docbook/publiccan challenges, please seek me out in #publican and i'll do my best to help out. >> > > Ok, migrations all did what I'd hoped but I am still seeing a "failed to > load external entity" issue. To reproduce: > > git clone git://git.fedorahosted.org/git/csi.git/ > make txt-all > > > -Mike Hi Mike, there doesn't appear to be any serious problems with your build. Below means you have empty para tags, which can prevent translations from being created or merged: *WARNING: Removing empty para tag from build environment, this may break your build* The warnings about unknown tags is letting you know that we haven't QA'd the output of those tags, so the default DocBook output will be used. The default DocBook output has be know to not be standards compliant and, in some cases, ugly. I am testing on the latest build from SVN, so let me know if you have any other errors. Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From jfearn at redhat.com Wed Oct 15 03:56:22 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Wed, 15 Oct 2008 13:56:22 +1000 Subject: [publican-list] perl-XML-TreeBuilder Fedora 8/9 updates need testing Message-ID: <48F569E6.3080906@redhat.com> I pushed a fix for perl-XML-TreeBuilder to overcome the crash when entities are defined in xml files. Please test :) https://admin.fedoraproject.org/updates/perl-XML-TreeBuilder-3.09-11.fc9 https://admin.fedoraproject.org/updates/perl-XML-TreeBuilder-3.09-11.fc8 Fix also pushed to rawhide. Publican 0.38 will probably be pushed Friday, Australian time, it requires this updated package. Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From jfearn at redhat.com Wed Oct 15 04:02:14 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Wed, 15 Oct 2008 14:02:14 +1000 Subject: [publican-list] Comments in XML files, good, bad, or ugly? Message-ID: <48F56B46.7070005@redhat.com> Currently when you run `make clean_ids` any comments using the format get removed. This was left in place as in some circumstances inline comments break translations as the merging process does not match the msgid. Is removing the comments the correct behaviour? I have no strong feelings on the subject and it is a fairly simple fix from publicans perspective. The translation issue is a problem with either po2xml or msgmerge and would need to be fixed upstream, assuing it hasn't already been fixed. Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From lbrindle at redhat.com Wed Oct 15 04:21:21 2008 From: lbrindle at redhat.com (Lana Brindley) Date: Wed, 15 Oct 2008 15:21:21 +1100 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F56B46.7070005@redhat.com> References: <48F56B46.7070005@redhat.com> Message-ID: <48F56FC1.3060501@redhat.com> Jeff Fearn wrote: > Currently when you run `make clean_ids` any comments using the format get removed. > > This was left in place as in some circumstances inline comments break > translations as the merging process does not match the msgid. > Is removing the comments the correct behaviour? > > I have no strong feelings on the subject and it is a fairly simple fix > from publicans perspective. The translation issue is a problem with > either po2xml or msgmerge and would need to be fixed upstream, assuing > it hasn't already been fixed. > > Cheers, Jeff. > Oh, are we re-opening this old argument discussion?? I was originally an advocate for keeping comments, this was because I lost a chunk of data through the make clean_ids behaviour, and got a little ... errr ... annoyed ;-) That said, over time (and with a bit of mellowing) it doesn't seem to me to be such a bad thing after all. The point has been raised that commenting is a standard function of any code, but the fact remains that, while we do indeed use a programming language (of sorts) to write our books, what we're doing is not coding, it's writing. We simply use the tags to define what our books look like (not how the books perform tasks, or complete functions, as does a program). Do comments belong in books? They certainly have their uses - we can use them to leave notes for ourselves (and any reviewers who prefer to review the source, rather than the output - whoever they are), but this can also be achieved through - the behaviour of which has changed now so that it doesn't print, which is great. What else are comments good for? Is there anything that can be achieved with comments that _can't_ be achieved through the use of another tag (like )? I personally can't find any good reason to keep them in, despite my best efforts. Perhaps that's just because I'm used to the behaviour now, and it's a case of better the devil you know? If anyone can come up with a compelling reason for changing the behaviour, I'd like to hear it :) L -------------- next part -------------- A non-text attachment was scrubbed... Name: lbrindle.vcf Type: text/x-vcard Size: 976 bytes Desc: not available URL: From jaredsmith at jaredsmith.net Wed Oct 15 04:27:04 2008 From: jaredsmith at jaredsmith.net (Jared Smith) Date: Wed, 15 Oct 2008 00:27:04 -0400 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F56FC1.3060501@redhat.com> References: <48F56B46.7070005@redhat.com> <48F56FC1.3060501@redhat.com> Message-ID: <1224044824.3577.50.camel@localhost.localdomain> On Wed, 2008-10-15 at 15:21 +1100, Lana Brindley wrote: > What else are comments good for? Is there anything that can be achieved > with comments that _can't_ be achieved through the use of another tag > (like )? I, for one, like to put a comment at the very bottom of my XML files that looks like: !-- vim: softtabstop=2:shiftwidth=2:expandtab:textwidth=72 --> I realize it's a pretty trivial example, but it's just a single example of one of the many places a just doesn't seem to fit. -Jared From jfearn at redhat.com Wed Oct 15 04:27:47 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Wed, 15 Oct 2008 14:27:47 +1000 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F56FC1.3060501@redhat.com> References: <48F56B46.7070005@redhat.com> <48F56FC1.3060501@redhat.com> Message-ID: <48F57143.30505@redhat.com> Lana Brindley wrote: -- snip interesting perspective -- > can also be achieved through - the behaviour of which has > changed now so that it doesn't print, which is great. Just to clarify, by default remarks are not printed. If you set SHOW_REMARKS = 1 in your Makefile, or SHOW_REMARKS=1 on the command line, remarks will be printed on a highlighted background. Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From lbrindle at redhat.com Wed Oct 15 04:29:14 2008 From: lbrindle at redhat.com (Lana Brindley) Date: Wed, 15 Oct 2008 15:29:14 +1100 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <1224044824.3577.50.camel@localhost.localdomain> References: <48F56B46.7070005@redhat.com> <48F56FC1.3060501@redhat.com> <1224044824.3577.50.camel@localhost.localdomain> Message-ID: <48F5719A.6090800@redhat.com> Jared Smith wrote: > On Wed, 2008-10-15 at 15:21 +1100, Lana Brindley wrote: >> What else are comments good for? Is there anything that can be achieved >> with comments that _can't_ be achieved through the use of another tag >> (like )? > > I, for one, like to put a comment at the very bottom of my XML files > that looks like: > > !-- > vim: softtabstop=2:shiftwidth=2:expandtab:textwidth=72 > --> > > I realize it's a pretty trivial example, but it's just a single example > of one of the many places a just doesn't seem to fit. > > -Jared > Jared, Skuse my ignorance ... but what does that line actually do? L -------------- next part -------------- A non-text attachment was scrubbed... Name: lbrindle.vcf Type: text/x-vcard Size: 976 bytes Desc: not available URL: From jfearn at redhat.com Wed Oct 15 04:43:33 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Wed, 15 Oct 2008 14:43:33 +1000 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F5719A.6090800@redhat.com> References: <48F56B46.7070005@redhat.com> <48F56FC1.3060501@redhat.com> <1224044824.3577.50.camel@localhost.localdomain> <48F5719A.6090800@redhat.com> Message-ID: <48F574F5.6060801@redhat.com> Lana Brindley wrote: > Jared Smith wrote: >> On Wed, 2008-10-15 at 15:21 +1100, Lana Brindley wrote: >>> What else are comments good for? Is there anything that can be >>> achieved with comments that _can't_ be achieved through the use of >>> another tag (like )? >> >> I, for one, like to put a comment at the very bottom of my XML files >> that looks like: >> >> !-- vim: softtabstop=2:shiftwidth=2:expandtab:textwidth=72 --> >> >> I realize it's a pretty trivial example, but it's just a single example >> of one of the many places a just doesn't seem to fit. >> >> -Jared > > Jared, > > Skuse my ignorance ... but what does that line actually do? It embeds vim configuration settings in the file, forcing other vim users to delete it and reload the file with the proper configuration settings. Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From lbrindle at redhat.com Wed Oct 15 04:49:36 2008 From: lbrindle at redhat.com (Lana Brindley) Date: Wed, 15 Oct 2008 15:49:36 +1100 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F574F5.6060801@redhat.com> References: <48F56B46.7070005@redhat.com> <48F56FC1.3060501@redhat.com> <1224044824.3577.50.camel@localhost.localdomain> <48F5719A.6090800@redhat.com> <48F574F5.6060801@redhat.com> Message-ID: <48F57660.9070700@redhat.com> Jeff Fearn wrote: > Lana Brindley wrote: >> Jared Smith wrote: >>> On Wed, 2008-10-15 at 15:21 +1100, Lana Brindley wrote: >>>> What else are comments good for? Is there anything that can be >>>> achieved with comments that _can't_ be achieved through the use of >>>> another tag (like )? >>> >>> I, for one, like to put a comment at the very bottom of my XML files >>> that looks like: >>> >>> !-- vim: softtabstop=2:shiftwidth=2:expandtab:textwidth=72 --> >>> >>> I realize it's a pretty trivial example, but it's just a single example >>> of one of the many places a just doesn't seem to fit. >>> >>> -Jared >> >> Jared, >> >> Skuse my ignorance ... but what does that line actually do? > > It embeds vim configuration settings in the file, forcing other vim > users to delete it and reload the file with the proper configuration > settings. > > Cheers, Jeff. > Who reads documentation in vim? L -------------- next part -------------- A non-text attachment was scrubbed... Name: lbrindle.vcf Type: text/x-vcard Size: 976 bytes Desc: not available URL: From jfearn at redhat.com Wed Oct 15 04:51:44 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Wed, 15 Oct 2008 14:51:44 +1000 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F57660.9070700@redhat.com> References: <48F56B46.7070005@redhat.com> <48F56FC1.3060501@redhat.com> <1224044824.3577.50.camel@localhost.localdomain> <48F5719A.6090800@redhat.com> <48F574F5.6060801@redhat.com> <48F57660.9070700@redhat.com> Message-ID: <48F576E0.1060709@redhat.com> Lana Brindley wrote: > Jeff Fearn wrote: >> Lana Brindley wrote: >>> Jared Smith wrote: >>>> On Wed, 2008-10-15 at 15:21 +1100, Lana Brindley wrote: >>>>> What else are comments good for? Is there anything that can be >>>>> achieved with comments that _can't_ be achieved through the use of >>>>> another tag (like )? >>>> >>>> I, for one, like to put a comment at the very bottom of my XML files >>>> that looks like: >>>> >>>> !-- vim: softtabstop=2:shiftwidth=2:expandtab:textwidth=72 --> >>>> >>>> I realize it's a pretty trivial example, but it's just a single example >>>> of one of the many places a just doesn't seem to fit. >>>> >>>> -Jared >>> >>> Jared, >>> >>> Skuse my ignorance ... but what does that line actually do? >> >> It embeds vim configuration settings in the file, forcing other vim >> users to delete it and reload the file with the proper configuration >> settings. >> >> Cheers, Jeff. >> > > Who reads documentation in vim? Probably just Jared and me :D Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From lbrindle at redhat.com Wed Oct 15 04:54:16 2008 From: lbrindle at redhat.com (Lana Brindley) Date: Wed, 15 Oct 2008 15:54:16 +1100 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F576E0.1060709@redhat.com> References: <48F56B46.7070005@redhat.com> <48F56FC1.3060501@redhat.com> <1224044824.3577.50.camel@localhost.localdomain> <48F5719A.6090800@redhat.com> <48F574F5.6060801@redhat.com> <48F57660.9070700@redhat.com> <48F576E0.1060709@redhat.com> Message-ID: <48F57778.1050001@redhat.com> Jeff Fearn wrote: > Lana Brindley wrote: >> Jeff Fearn wrote: >>> Lana Brindley wrote: >>>> Jared Smith wrote: >>>>> On Wed, 2008-10-15 at 15:21 +1100, Lana Brindley wrote: >>>>>> What else are comments good for? Is there anything that can be >>>>>> achieved with comments that _can't_ be achieved through the use of >>>>>> another tag (like )? >>>>> >>>>> I, for one, like to put a comment at the very bottom of my XML files >>>>> that looks like: >>>>> >>>>> !-- vim: softtabstop=2:shiftwidth=2:expandtab:textwidth=72 --> >>>>> >>>>> I realize it's a pretty trivial example, but it's just a single >>>>> example >>>>> of one of the many places a just doesn't seem to fit. >>>>> >>>>> -Jared >>>> >>>> Jared, >>>> >>>> Skuse my ignorance ... but what does that line actually do? >>> >>> It embeds vim configuration settings in the file, forcing other vim >>> users to delete it and reload the file with the proper configuration >>> settings. >>> >>> Cheers, Jeff. >>> >> >> Who reads documentation in vim? > > Probably just Jared and me :D > > Cheers, Jeff. > Huh. Figures. :-P L -------------- next part -------------- A non-text attachment was scrubbed... Name: lbrindle.vcf Type: text/x-vcard Size: 976 bytes Desc: not available URL: From jaredsmith at jaredsmith.net Wed Oct 15 13:15:39 2008 From: jaredsmith at jaredsmith.net (Jared Smith) Date: Wed, 15 Oct 2008 13:15:39 +0000 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F57660.9070700@redhat.com> References: <48F56B46.7070005@redhat.com> <48F56FC1.3060501@redhat.com> <1224044824.3577.50.camel@localhost.localdomain> <48F5719A.6090800@redhat.com> <48F574F5.6060801@redhat.com> <48F57660.9070700@redhat.com> Message-ID: <1224076539.3577.59.camel@localhost.localdomain> On Wed, 2008-10-15 at 15:49 +1100, Lana Brindley wrote: > Who reads documentation in vim? Not only am I sick and twisted enough to read documentation in vim, I actually write books in DocBook in vim. Scary, isn't it?!? To add additional clarification, however, that vim command is something I picked up from the Fedora Documentation team, and they have something similar for emacs as well. All in all, it looks something like: Yes, some people don't like it, as it overrides their own personal settings. At the same time, it makes it much cleaner for working with tabs, etc. when working in a group environment. I'm not saying it's a perfect fit for anyone (myself included), but I thought I'd throw it out there for two reasons: first as an example of where a remark would be cumbersome (if not impossible), and second just in case anyone on the list (or in the archives later) finds it useful for them. -Jared From jonathan.robie at redhat.com Wed Oct 15 13:41:14 2008 From: jonathan.robie at redhat.com (Jonathan Robie) Date: Wed, 15 Oct 2008 09:41:14 -0400 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F57778.1050001@redhat.com> References: <48F56B46.7070005@redhat.com> <48F56FC1.3060501@redhat.com> <1224044824.3577.50.camel@localhost.localdomain> <48F5719A.6090800@redhat.com> <48F574F5.6060801@redhat.com> <48F57660.9070700@redhat.com> <48F576E0.1060709@redhat.com> <48F57778.1050001@redhat.com> Message-ID: <48F5F2FA.2060406@redhat.com> I really wish comments were kept by default, and I'd like CDATA sections to be preserved by default. A target that strips comments and replaces CDATAsections using character entities woujld be fine. I like comments to embed version history in files: These comments automatically register the changes from the change logs, which makes it easier to write the revision logs at the end of the process. I use comments for todo-lists within the text; I like them in the text where they don't get lost, and I don't see a lot of reason to mark these up. They do need to be cleaned up or stripped before delevering the source, though. For code examples, I find it useful to be able to drop source code chunks into CDATA sections and immediately see that they look like the original text: TCP/IP Illustrated Stevens Addison-Wesley Advanced Programming in the Unix Environment Stevens Addison-Wesley Data on the Web Abiteboul Buneman Suciu ]]> I can just look at that and know it's an example with well-formed XML. I can't do that if you remove the CDATA section and use character entities. Jonathan From stickster at gmail.com Wed Oct 15 16:09:49 2008 From: stickster at gmail.com (Paul W. Frields) Date: Wed, 15 Oct 2008 12:09:49 -0400 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F5F2FA.2060406@redhat.com> References: <48F56B46.7070005@redhat.com> <48F56FC1.3060501@redhat.com> <1224044824.3577.50.camel@localhost.localdomain> <48F5719A.6090800@redhat.com> <48F574F5.6060801@redhat.com> <48F57660.9070700@redhat.com> <48F576E0.1060709@redhat.com> <48F57778.1050001@redhat.com> <48F5F2FA.2060406@redhat.com> Message-ID: <1224086989.22899.12.camel@victoria-eth.internal.frields.org> On Wed, 2008-10-15 at 09:41 -0400, Jonathan Robie wrote: > For code examples, I find it useful to be able to drop source code > chunks into CDATA sections and immediately see that they look like the > original text: > > > TCP/IP Illustrated > Stevens > Addison-Wesley > > > Advanced Programming in the Unix Environment > Stevens > Addison-Wesley > > > Data on the Web > Abiteboul > Buneman > Suciu > > ]]> > > I can just look at that and know it's an example with well-formed XML. I > can't do that if you remove the CDATA section and use character entities. I use this method very often, too. -- Paul W. Frields gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 http://paul.frields.org/ - - http://pfrields.fedorapeople.org/ irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From dhensley at redhat.com Wed Oct 15 20:44:28 2008 From: dhensley at redhat.com (Douglas Silas Hensley) Date: Wed, 15 Oct 2008 22:44:28 +0200 Subject: [publican-list] Comments in XML files, good, bad, or ugly?] Message-ID: <48F6562C.6040706@redhat.com> Hi, I'm definitely an advocate for retaining comments, which are obviously useful. Anything that helps the writers should be retained. And I disagree that we're just writers and shouldn't be doing "coding/programming" :-) I know that I am, along with others, trying to write modular documentation with little duplication, because I don't want to have the same content in multiple places that will have to be updated separately in the future. Comments, for me, are a way to keep track, at the site, of what's going on and how I've structured the documentation, among other uses. Also, I can comment in OpenOffice, so that's not a function that's just relegated to coding (apologies if I have asserted something not accurate here). Also, maven-jdocbook shows the text of by default, which could throw someone for a loop. I'm sure you can turn that off as well (not that finding out how will be easy), but I don't see the point of using for comments ( could be reserved for other useful purposes). And you might not miss something until it's gone... (plus, it truly can be useful for editors, even non-vim ones) +1 pro-comment Cheers, Silas Lana Brindley wrote: > Jeff Fearn wrote: >> Currently when you run `make clean_ids` any comments using the format get removed. >> >> This was left in place as in some circumstances inline comments break >> translations as the merging process does not match the msgid. >> Is removing the comments the correct behaviour? >> >> I have no strong feelings on the subject and it is a fairly simple fix >> from publicans perspective. The translation issue is a problem with >> either po2xml or msgmerge and would need to be fixed upstream, assuing >> it hasn't already been fixed. >> >> Cheers, Jeff. >> > > Oh, are we re-opening this old argument discussion?? > > I was originally an advocate for keeping comments, this was because I > lost a chunk of data through the make clean_ids behaviour, and got a > little ... errr ... annoyed ;-) > > That said, over time (and with a bit of mellowing) it doesn't seem to me > to be such a bad thing after all. The point has been raised that > commenting is a standard function of any code, but the fact remains > that, while we do indeed use a programming language (of sorts) to write > our books, what we're doing is not coding, it's writing. We simply use > the tags to define what our books look like (not how the books perform > tasks, or complete functions, as does a program). > > Do comments belong in books? They certainly have their uses - we can use > them to leave notes for ourselves (and any reviewers who prefer to > review the source, rather than the output - whoever they are), but this > can also be achieved through - the behaviour of which has > changed now so that it doesn't print, which is great. > > What else are comments good for? Is there anything that can be achieved > with comments that _can't_ be achieved through the use of another tag > (like )? > > I personally can't find any good reason to keep them in, despite my best > efforts. Perhaps that's just because I'm used to the behaviour now, and > it's a case of better the devil you know? If anyone can come up with a > compelling reason for changing the behaviour, I'd like to hear it :) > > L > > _______________________________________________ > publican-list mailing list > publican-list at redhat.com > https://www.redhat.com/mailman/listinfo/publican-list > Wiki: https://fedorahosted.org/publican -- Douglas Silas Technical Writer | Red Hat, Inc. Purky?ova 99 | Brno, Czech Republic Office Direct Dial?62116 Brno Office?(+420) 532 294 116 dhensley at redhat.com -- Douglas Silas Technical Writer | Red Hat, Inc. Purky?ova 99 | Brno, Czech Republic Office Direct Dial?62116 Brno Office?(+420) 532 294 116 dhensley at redhat.com From mhideo at redhat.com Wed Oct 15 21:49:32 2008 From: mhideo at redhat.com (Michael Hideo-Smith) Date: Wed, 15 Oct 2008 17:49:32 -0400 (EDT) Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F56B46.7070005@redhat.com> Message-ID: <438355720.970001224107372659.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> ----- "Jeff Fearn" wrote: > From: "Jeff Fearn" > To: "publican" > Sent: Wednesday, October 15, 2008 2:02:14 PM GMT +10:00 Brisbane > Subject: [publican-list] Comments in XML files, good, bad, or ugly? > > Currently when you run `make clean_ids` any comments using the format get removed. > > This was left in place as in some circumstances inline comments break > translations as the merging process does not match the msgid. Hi Jeff, I am in favour of preserving comments during the clean_ids routine. It has always been the in-line comments that break translation. ie this is bad: So then Mary said, these codes sample in BZ4333 no worky worky for me. ie this is good So then Mary said, this codes sample in BZ4333 no worky worky for me. - Mike From lbrindle at redhat.com Wed Oct 15 21:52:43 2008 From: lbrindle at redhat.com (Lana Brindley) Date: Thu, 16 Oct 2008 08:52:43 +1100 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F5F2FA.2060406@redhat.com> References: <48F56B46.7070005@redhat.com> <48F56FC1.3060501@redhat.com> <1224044824.3577.50.camel@localhost.localdomain> <48F5719A.6090800@redhat.com> <48F574F5.6060801@redhat.com> <48F57660.9070700@redhat.com> <48F576E0.1060709@redhat.com> <48F57778.1050001@redhat.com> <48F5F2FA.2060406@redhat.com> Message-ID: <48F6662B.1070301@redhat.com> Jonathan Robie wrote: > I really wish comments were kept by default, and I'd like CDATA > sections to be preserved by default. A target that strips comments and > replaces CDATAsections using character entities woujld be fine. > > I like comments to embed version history in files: > > > These comments automatically register the changes from the change logs, > which makes it easier to write the revision logs at the end of the process. I hadn't thought of it for this purpose. Although there's something in me that wants to say - but that's why we have a revision history. What benefit does embedded version history have over the way we do it now? > > I use comments for todo-lists within the text; > > > > > > I like them in the text where they don't get lost, and I don't see a lot > of reason to mark these up. They do need to be cleaned up or stripped > before delevering the source, though. > This was my original thought for where comments were useful too, but I think serves the same purpose. In fact, that's exactly what I use for now. > > For code examples, I find it useful to be able to drop source code > chunks into CDATA sections and immediately see that they look like the > original text: > > > TCP/IP Illustrated > Stevens > Addison-Wesley > > > Advanced Programming in the Unix Environment > Stevens > Addison-Wesley > > > Data on the Web > Abiteboul > Buneman > Suciu > > ]]> > > I can just look at that and know it's an example with well-formed XML. I > can't do that if you remove the CDATA section and use character entities. > I think the CDATA stuff may possibly be (from Jeff's point of view, anyway) a different argument. CDATA definitely has its uses, especially for the type of stuff that Jonathan and I have been working on with MRG. I do believe there are some extenuating circumstances with CDATA and how Publican handles verbatim text though, so I'll let Jeff respond to that! > Jonathan > > Cheers, Lana -------------- next part -------------- A non-text attachment was scrubbed... Name: lbrindle.vcf Type: text/x-vcard Size: 976 bytes Desc: not available URL: From mhideo at redhat.com Wed Oct 15 22:03:44 2008 From: mhideo at redhat.com (Michael Hideo-Smith) Date: Wed, 15 Oct 2008 18:03:44 -0400 (EDT) Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F6662B.1070301@redhat.com> Message-ID: <61636331.974041224108224578.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> ----- "Lana Brindley" wrote: > From: "Lana Brindley" > To: "Jonathan Robie" > Cc: "publican" > Sent: Thursday, October 16, 2008 7:52:43 AM GMT +10:00 Brisbane > Subject: Re: [publican-list] Comments in XML files, good, bad, or ugly? > > I think the CDATA stuff may possibly be (from Jeff's point of view, > anyway) a different argument. CDATA definitely has its uses, > especially for the type of stuff that Jonathan and I have been working on with > MRG. > I do believe there are some extenuating circumstances with CDATA and > how Publican handles verbatim text though, so I'll let Jeff respond to > that! CDATA is extremely important to the writers in the java space. specifically, jboss. as it allows them to feed the code from docbook into their test harness. From lbrindle at redhat.com Wed Oct 15 22:11:43 2008 From: lbrindle at redhat.com (Lana Brindley) Date: Thu, 16 Oct 2008 09:11:43 +1100 Subject: [publican-list] Comments in XML files, good, bad, or ugly?] In-Reply-To: <48F6562C.6040706@redhat.com> References: <48F6562C.6040706@redhat.com> Message-ID: <48F66A9F.4030307@redhat.com> Yay for top posting! ;-) Silas, I guess I'm in a position where I don't use it, so I don't really mind if it's there or not. With that in mind, perhaps we should be looking at it like a choice matter. If we leave the ability out, then no one can use it. If we put it in, then writers can choose to use it or not, depending on how they work. L Douglas Silas Hensley wrote: > Hi, > > I'm definitely an advocate for retaining comments, which are > obviously useful. Anything that helps the writers should be retained. > > And I disagree that we're just writers and shouldn't be doing > "coding/programming" :-) I know that I am, along with others, trying > to write modular documentation with little duplication, because I > don't want to have the same content in multiple places that will > have to be updated separately in the future. Comments, for me, are a > way to keep track, at the site, of what's going on and how I've > structured the documentation, among other uses. > > Also, I can comment in OpenOffice, so that's not a function that's > just relegated to coding (apologies if I have asserted something not > accurate here). > > Also, maven-jdocbook shows the text of by default, which > could throw someone for a loop. I'm sure you can turn that off as > well (not that finding out how will be easy), but I don't see the > point of using for comments ( could be reserved > for other useful purposes). > > And you might not miss something until it's gone... (plus, it truly > can be useful for editors, even non-vim ones) > > +1 pro-comment > > Cheers, > > Silas > > Lana Brindley wrote: >> Jeff Fearn wrote: >>> Currently when you run `make clean_ids` any comments using the format get removed. >>> >>> This was left in place as in some circumstances inline comments break >>> translations as the merging process does not match the msgid. >>> Is removing the comments the correct behaviour? >>> >>> I have no strong feelings on the subject and it is a fairly simple fix >>> from publicans perspective. The translation issue is a problem with >>> either po2xml or msgmerge and would need to be fixed upstream, assuing >>> it hasn't already been fixed. >>> >>> Cheers, Jeff. >>> >> Oh, are we re-opening this old argument discussion?? >> >> I was originally an advocate for keeping comments, this was because I >> lost a chunk of data through the make clean_ids behaviour, and got a >> little ... errr ... annoyed ;-) >> >> That said, over time (and with a bit of mellowing) it doesn't seem to me >> to be such a bad thing after all. The point has been raised that >> commenting is a standard function of any code, but the fact remains >> that, while we do indeed use a programming language (of sorts) to write >> our books, what we're doing is not coding, it's writing. We simply use >> the tags to define what our books look like (not how the books perform >> tasks, or complete functions, as does a program). >> >> Do comments belong in books? They certainly have their uses - we can use >> them to leave notes for ourselves (and any reviewers who prefer to >> review the source, rather than the output - whoever they are), but this >> can also be achieved through - the behaviour of which has >> changed now so that it doesn't print, which is great. >> >> What else are comments good for? Is there anything that can be achieved >> with comments that _can't_ be achieved through the use of another tag >> (like )? >> >> I personally can't find any good reason to keep them in, despite my best >> efforts. Perhaps that's just because I'm used to the behaviour now, and >> it's a case of better the devil you know? If anyone can come up with a >> compelling reason for changing the behaviour, I'd like to hear it :) >> >> L >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > -------------- next part -------------- A non-text attachment was scrubbed... Name: lbrindle.vcf Type: text/x-vcard Size: 1006 bytes Desc: not available URL: From jfearn at redhat.com Wed Oct 15 22:43:47 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Thu, 16 Oct 2008 08:43:47 +1000 Subject: [publican-list] Comments in XML files, good, bad, or ugly? In-Reply-To: <48F5F2FA.2060406@redhat.com> References: <48F56B46.7070005@redhat.com> <48F56FC1.3060501@redhat.com> <1224044824.3577.50.camel@localhost.localdomain> <48F5719A.6090800@redhat.com> <48F574F5.6060801@redhat.com> <48F57660.9070700@redhat.com> <48F576E0.1060709@redhat.com> <48F57778.1050001@redhat.com> <48F5F2FA.2060406@redhat.com> Message-ID: <48F67223.4090902@redhat.com> Jonathan Robie wrote: > I really wish comments were kept by default, and I'd like CDATA > sections to be preserved by default. A target that strips comments and > replaces CDATAsections using character entities woujld be fine. > > I like comments to embed version history in files: For me this is an excellent example of the type of content a reviewer might like to see when reviewing a document, which would fit better with a remark than a comment. Given that no one has supported excluding comments I will add support for them. ---snip--- > For code examples, I find it useful to be able to drop source code > chunks into CDATA sections and immediately see that they look like the > original text: > > > TCP/IP Illustrated > Stevens > Addison-Wesley > > > Advanced Programming in the Unix Environment > Stevens > Addison-Wesley > > > Data on the Web > Abiteboul > Buneman > Suciu > > ]]> > > I can just look at that and know it's an example with well-formed XML. I > can't do that if you remove the CDATA section and use character entities. CDATA is an evil, dirty hack that only existed because there wasn't a way to cleanly handle un-escaped textual content. If the only options were CDATA or escaped textual content, then I too would probably choose CDATA. There is a third option which allows clean handling of un-escaped textual content, publican encourages this third option. This third option is particularly useful when you are getting code examples from developers. It allows developers to give you examples in the format they work with. A java programmer could supply you with .java files that you would not have to edit. They could test these in their proper environment and just email or check in the .java files. If they updated their examples they could simply supply an updated .java file. Your XML never needs to be updated once the .java file is included! >From the publican users guide, faq chapter (http://jfearn.fedorapeople.org/Publican/chap-Publican-Frequently_Asked_Questions.html) Q: I have extensive code samples for my book, how can I include them without having to xml escape everything? A: The best way to do this is to create a directory named extras in your source language directory and use an xi:include to pull in the code file. Procedure 5.1. Including code samples 1. Create the extras directory mkdir en-US/extras 2. Copy the code file to the extras directory cp ~/samples/foo.c en-US/extras/. 3. xi:include the sample file in your xml file 4. You can now edit en-US/extras/foo.c in your favorite editor without having to be concerned about how it will affect the XML. IMHO this is a _much_ cleaner way of handling un-escaped textual content. Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From bugzilla at redhat.com Wed Oct 15 23:10:42 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Wed, 15 Oct 2008 19:10:42 -0400 Subject: [publican-list] [Bug 467145] New: clean_ids should not remove comments Message-ID: Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. Summary: clean_ids should not remove comments https://bugzilla.redhat.com/show_bug.cgi?id=467145 Summary: clean_ids should not remove comments Product: Red Hat Enterprise Linux 5 Version: 5.4 Platform: All OS/Version: Linux Status: NEW Severity: medium Priority: medium Component: publican AssignedTo: jfearn at redhat.com ReportedBy: jfearn at redhat.com QAContact: ecs-dev-list at redhat.com CC: publican-list at redhat.com Classification: Red Hat Description of problem: The clean_ids make target currently removes comments from the XML when processing. Version-Release number of selected component (if applicable): publican-0.37 How reproducible: Always Steps to Reproduce: 1. Add a comment using format get removed. >> >> This was left in place as in some circumstances inline comments break >> translations as the merging process does not match the msgid. >> > > Hi Jeff, > > I am in favour of preserving comments during the clean_ids routine. It has always been the in-line comments that break translation. > > ie this is bad: > > So then Mary said, these codes sample in BZ4333 no worky worky for me. > > ie this is good > > > So then Mary said, this codes sample in BZ4333 no worky worky for me. > +1 Jonathan From bugzilla at redhat.com Thu Oct 16 22:44:04 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 16 Oct 2008 18:44:04 -0400 Subject: [publican-list] [Bug 467145] clean_ids should not remove comments In-Reply-To: References: Message-ID: <200810162244.m9GMi4U2008730@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=467145 --- Comment #2 from Fedora Update System 2008-10-16 18:44:03 EDT --- publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 has been submitted as an update for Fedora 9. http://admin.fedoraproject.org/updates/publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Thu Oct 16 22:43:41 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 16 Oct 2008 18:43:41 -0400 Subject: [publican-list] [Bug 462673] mangled spacing with >=10 items in an orderedlist In-Reply-To: References: Message-ID: <200810162243.m9GMhfNB008631@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=462673 --- Comment #2 from Fedora Update System 2008-10-16 18:43:40 EDT --- publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 has been submitted as an update for Fedora 9. http://admin.fedoraproject.org/updates/publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Thu Oct 16 22:43:48 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 16 Oct 2008 18:43:48 -0400 Subject: [publican-list] [Bug 462991] Increase space before Glossary and Appendix entries in TOC In-Reply-To: References: Message-ID: <200810162243.m9GMhmJg008677@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=462991 --- Comment #2 from Fedora Update System 2008-10-16 18:43:47 EDT --- publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 has been submitted as an update for Fedora 9. http://admin.fedoraproject.org/updates/publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Thu Oct 16 22:43:45 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 16 Oct 2008 18:43:45 -0400 Subject: [publican-list] [Bug 462205] RFE: make test and html, no errors when number of cells is more than the specified value In-Reply-To: References: Message-ID: <200810162243.m9GMhjX3008655@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=462205 --- Comment #4 from Fedora Update System 2008-10-16 18:43:45 EDT --- publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 has been submitted as an update for Fedora 9. http://admin.fedoraproject.org/updates/publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Thu Oct 16 22:43:50 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 16 Oct 2008 18:43:50 -0400 Subject: [publican-list] [Bug 462552] syntax highlighting xml comments difficult to read In-Reply-To: References: Message-ID: <200810162243.m9GMho69011329@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=462552 --- Comment #3 from Fedora Update System 2008-10-16 18:43:49 EDT --- publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 has been submitted as an update for Fedora 9. http://admin.fedoraproject.org/updates/publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Thu Oct 16 22:43:52 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 16 Oct 2008 18:43:52 -0400 Subject: [publican-list] [Bug 464038] RFE: please support citerefentry, refentrytitle, and manvolnum In-Reply-To: References: Message-ID: <200810162243.m9GMhqJg011351@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=464038 --- Comment #2 from Fedora Update System 2008-10-16 18:43:52 EDT --- publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 has been submitted as an update for Fedora 9. http://admin.fedoraproject.org/updates/publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Thu Oct 16 22:43:38 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 16 Oct 2008 18:43:38 -0400 Subject: [publican-list] [Bug 463127] Examples in PDFs are not easily distinguishable from ordinary text In-Reply-To: References: Message-ID: <200810162243.m9GMhct8011278@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=463127 --- Comment #3 from Fedora Update System 2008-10-16 18:43:38 EDT --- publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 has been submitted as an update for Fedora 9. http://admin.fedoraproject.org/updates/publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Thu Oct 16 22:44:06 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 16 Oct 2008 18:44:06 -0400 Subject: [publican-list] [Bug 467147] Insufficient error reporting when no revision history is present. In-Reply-To: References: Message-ID: <200810162244.m9GMi6ni011451@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=467147 --- Comment #3 from Fedora Update System 2008-10-16 18:44:06 EDT --- publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 has been submitted as an update for Fedora 9. http://admin.fedoraproject.org/updates/publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Thu Oct 16 22:43:55 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 16 Oct 2008 18:43:55 -0400 Subject: [publican-list] [Bug 465411] PDF build adds "1" characters into URLs, causing links to fail if people highlight and copy In-Reply-To: References: Message-ID: <200810162243.m9GMhtv9011377@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=465411 --- Comment #5 from Fedora Update System 2008-10-16 18:43:54 EDT --- publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 has been submitted as an update for Fedora 9. http://admin.fedoraproject.org/updates/publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From jfearn at redhat.com Thu Oct 16 22:48:54 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Fri, 17 Oct 2008 08:48:54 +1000 Subject: [publican-list] Version 0.38 in F-9 testing Message-ID: <48F7C4D6.1020602@redhat.com> All that spam is because I pushed publican 0.38 and perl-XML-TreeBuilder 3.09-11 in to RawHide and F-9. https://admin.fedoraproject.org/updates/publican-0.38-0.fc9,perl-XML-TreeBuilder-3.09-11.fc9 You need both these packages. Please test :) Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From bugzilla at redhat.com Fri Oct 17 04:05:49 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 17 Oct 2008 00:05:49 -0400 Subject: [publican-list] [Bug 461076] revise publican-jboss legal notice In-Reply-To: References: Message-ID: <200810170405.m9H45nRb023712@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461076 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Priority|low |urgent CC| |jfearn at redhat.com Severity|low |urgent --- Comment #1 from Jeff Fearn 2008-10-17 00:05:48 EDT --- Legal questions should be dealt with immediately. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Fri Oct 17 04:10:30 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 17 Oct 2008 00:10:30 -0400 Subject: [publican-list] [Bug 453246] Linux trademark attribution for legal notice In-Reply-To: References: Message-ID: <200810170410.m9H4AUiH027045@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=453246 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Priority|medium |urgent CC| |jfearn at redhat.com Severity|medium |urgent --- Comment #2 from Jeff Fearn 2008-10-17 00:10:29 EDT --- Legal issues should be fixed ASAP -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Fri Oct 17 04:15:20 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 17 Oct 2008 00:15:20 -0400 Subject: [publican-list] [Bug 448022] please revise legal notices In-Reply-To: References: Message-ID: <200810170415.m9H4FKjh027780@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=448022 Murray McAllister changed: What |Removed |Added ---------------------------------------------------------------------------- Status|MODIFIED |CLOSED Fixed In Version| |0.38 Resolution| |CURRENTRELEASE -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Fri Oct 17 04:16:16 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 17 Oct 2008 00:16:16 -0400 Subject: [publican-list] [Bug 448022] please revise legal notices In-Reply-To: References: Message-ID: <200810170416.m9H4GGxZ025336@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=448022 Murray McAllister changed: What |Removed |Added ---------------------------------------------------------------------------- Fixed In Version|0.38 |0.15 -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Fri Oct 17 05:15:25 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 17 Oct 2008 01:15:25 -0400 Subject: [publican-list] [Bug 467368] New: figure border does not match image in html Message-ID: Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. Summary: figure border does not match image in html https://bugzilla.redhat.com/show_bug.cgi?id=467368 Summary: figure border does not match image in html Product: Red Hat Enterprise Linux 5 Version: 5.2 Platform: All OS/Version: Linux Status: NEW Severity: medium Priority: medium Component: publican AssignedTo: jfearn at redhat.com ReportedBy: dmison at redhat.com QAContact: ecs-dev-list at redhat.com CC: publican-list at redhat.com Classification: Red Hat Description of problem: If you supply the width attribute in the html output puts a very cool border around the image. However this border fills the whole width of the page, not the width of the image. Version-Release number of selected component (if applicable): publican-0.38-0.el5 How reproducible: everytime Steps to Reproduce: Actual results: attached image Expected results: border should be a consistant distance from all edges of the image Additional info: The border doesn't get rendered at all in the pdf output. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Fri Oct 17 05:17:13 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 17 Oct 2008 01:17:13 -0400 Subject: [publican-list] [Bug 467368] figure border does not match image in html In-Reply-To: References: Message-ID: <200810170517.m9H5HDRU004044@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=467368 --- Comment #1 from Darrin Mison 2008-10-17 01:17:13 EDT --- Created an attachment (id=320638) --> (https://bugzilla.redhat.com/attachment.cgi?id=320638) actual output -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Fri Oct 17 05:17:58 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 17 Oct 2008 01:17:58 -0400 Subject: [publican-list] [Bug 467368] border does not match image in html In-Reply-To: References: Message-ID: <200810170517.m9H5HwIh004098@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=467368 Darrin Mison changed: What |Removed |Added ---------------------------------------------------------------------------- Summary|figure border does not |border does not match image |match image in html |in html -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Fri Oct 17 05:21:05 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 17 Oct 2008 01:21:05 -0400 Subject: [publican-list] [Bug 461076] revise publican-jboss legal notice In-Reply-To: References: Message-ID: <200810170521.m9H5L50R001821@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=461076 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |ASSIGNED -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Fri Oct 17 05:53:19 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 17 Oct 2008 01:53:19 -0400 Subject: [publican-list] [Bug 467368] border does not match image in html In-Reply-To: References: Message-ID: <200810170553.m9H5rJMv008713@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=467368 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |CLOSED Fixed In Version| |0.39 Resolution| |CURRENTRELEASE --- Comment #2 from Jeff Fearn 2008-10-17 01:53:18 EDT --- The bug here was that the border was being rendered at all. Removed border from HTML output when image width is set. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From jfearn at redhat.com Sun Oct 19 21:52:52 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Mon, 20 Oct 2008 07:52:52 +1000 Subject: [publican-list] Support for commercial software, yay or nay? Message-ID: <48FBAC34.4050209@redhat.com> Hi, recently a bug was opened raising an issue related to supporting commercial software in publican, thought I'd chuck it up here for discussion. The default DocBook XSL includes support for a number of commercial XSLT processors. When I customise the XSL I usually remove this support as I can not test how my changes have affected those processors and I don't like shipping stuff I can't test. I missed pulling out xep support in one place and a ticket resulted: https://bugzilla.redhat.com/show_bug.cgi?id=467256 While I won't go out of my way to break support for commercial software, I don't really feel like supporting them for free either. Discuss! Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From kanarip at kanarip.com Sun Oct 19 22:13:36 2008 From: kanarip at kanarip.com (Jeroen van Meeuwen) Date: Mon, 20 Oct 2008 00:13:36 +0200 Subject: [publican-list] Support for commercial software, yay or nay? In-Reply-To: <48FBAC34.4050209@redhat.com> References: <48FBAC34.4050209@redhat.com> Message-ID: <1224454416.25549.17.camel@ghandalf.kanarip.com> On Mon, 2008-10-20 at 07:52 +1000, Jeff Fearn wrote: > Hi, recently a bug was opened raising an issue related to supporting commercial software in publican, thought I'd chuck it up here for discussion. > > The default DocBook XSL includes support for a number of commercial XSLT processors. When I customise the XSL I usually remove this support as I can not test how my changes have affected those processors and I don't like shipping stuff I can't test. I missed pulling out xep support in one place and a ticket resulted: https://bugzilla.redhat.com/show_bug.cgi?id=467256 > > While I won't go out of my way to break support for commercial software, I don't really feel like supporting them for free either. > > Discuss! > If the tool-chain can be there, it is certainly added value, but I think it is very important to be able to choose not to use anything proprietary or patent-encumbered. Kind regards, Jeroen van Meeuwen -kanarip From bugzilla at redhat.com Mon Oct 20 02:07:53 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Sun, 19 Oct 2008 22:07:53 -0400 Subject: [publican-list] [Bug 467654] corners missing on when it contains or In-Reply-To: References: Message-ID: <200810200207.m9K27rLh013201@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=467654 --- Comment #2 from Darrin Mison 2008-10-19 22:07:52 EDT --- Created an attachment (id=320833) --> (https://bugzilla.redhat.com/attachment.cgi?id=320833) expected output -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Mon Oct 20 02:06:59 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Sun, 19 Oct 2008 22:06:59 -0400 Subject: [publican-list] [Bug 467654] New: corners missing on when it contains or Message-ID: Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. Summary: corners missing on when it contains or https://bugzilla.redhat.com/show_bug.cgi?id=467654 Summary: corners missing on when it contains or Product: Red Hat Enterprise Linux 5 Version: 5.2 Platform: All OS/Version: Linux Status: NEW Severity: medium Priority: medium Component: publican AssignedTo: jfearn at redhat.com ReportedBy: dmison at redhat.com QAContact: ecs-dev-list at redhat.com CC: publican-list at redhat.com Classification: Red Hat Description of problem: If you embed or in an tag the right hand corners have a "chunk taken out of them" in the pdf output. Version-Release number of selected component (if applicable): publican-0.38-0.el5 How reproducible: Everytime Steps to Reproduce: Service discovery period setting <entry key="rhq.agent.plugins.service-discovery.period-secs" value="86400"/> Actual results: attached screenshot actual.png Expected results: attached screenshot expected.png Additional info: Renders fine in html -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Mon Oct 20 02:07:31 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Sun, 19 Oct 2008 22:07:31 -0400 Subject: [publican-list] [Bug 467654] corners missing on when it contains or In-Reply-To: References: Message-ID: <200810200207.m9K27VAP017505@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=467654 --- Comment #1 from Darrin Mison 2008-10-19 22:07:30 EDT --- Created an attachment (id=320832) --> (https://bugzilla.redhat.com/attachment.cgi?id=320832) actual output -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From mmcgrath at redhat.com Wed Oct 22 15:00:09 2008 From: mmcgrath at redhat.com (Mike McGrath) Date: Wed, 22 Oct 2008 10:00:09 -0500 (CDT) Subject: [publican-list] draft support? Message-ID: Is there any way to declare a chapter book or set as a draft and have it get labeled as such when its built? I've seen draft watermarks for example but I'm not sure how they get added. -Mike From stickster at gmail.com Wed Oct 22 15:10:26 2008 From: stickster at gmail.com (Paul W. Frields) Date: Wed, 22 Oct 2008 15:10:26 +0000 Subject: [publican-list] draft support? In-Reply-To: References: Message-ID: <1224688226.11063.43.camel@localhost.localdomain> On Wed, 2008-10-22 at 10:00 -0500, Mike McGrath wrote: > Is there any way to declare a chapter book or set as a draft and have it > get labeled as such when its built? I've seen draft watermarks for > example but I'm not sure how they get added. Just FYI, the Fedora Docs toolchain does this with CSS, and a flag in our Makefile that copies the appropriate watermark if needed. -- Paul W. Frields gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 http://paul.frields.org/ - - http://pfrields.fedorapeople.org/ irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From jonathan.robie at redhat.com Wed Oct 22 15:35:35 2008 From: jonathan.robie at redhat.com (Jonathan Robie) Date: Wed, 22 Oct 2008 11:35:35 -0400 Subject: [publican-list] draft support? In-Reply-To: References: Message-ID: <48FF4847.3020407@redhat.com> Mike McGrath wrote: > Is there any way to declare a chapter book or set as a draft and have it > get labeled as such when its built? I've seen draft watermarks for > example but I'm not sure how they get added. > Should be able to set the draft.watermark.image parameter to the image you want: http://docbook.sourceforge.net/release/xsl/current/doc/html/draft.watermark.image.html Publican seems to come with a bunch of watermark images: http://docbook.sourceforge.net/release/xsl/current/doc/html/draft.watermark.image.html Hope this helps! Jonathan From jonathan.robie at redhat.com Wed Oct 22 15:46:29 2008 From: jonathan.robie at redhat.com (Jonathan Robie) Date: Wed, 22 Oct 2008 11:46:29 -0400 Subject: [publican-list] draft support? In-Reply-To: <48FF4847.3020407@redhat.com> References: <48FF4847.3020407@redhat.com> Message-ID: <48FF4AD5.3030905@redhat.com> Jonathan Robie wrote: > Publican seems to come with a bunch of watermark images: Oops, my cut/paste was supposed to say: $ rpm -qal publican | grep watermark Hope this helps! Jonathan From jaredsmith at jaredsmith.net Wed Oct 22 15:54:27 2008 From: jaredsmith at jaredsmith.net (Jared Smith) Date: Wed, 22 Oct 2008 11:54:27 -0400 Subject: [publican-list] draft support? In-Reply-To: <48FF4847.3020407@redhat.com> References: <48FF4847.3020407@redhat.com> Message-ID: <1224690867.19516.1.camel@localhost.localdomain> On Wed, 2008-10-22 at 11:35 -0400, Jonathan Robie wrote: > Should be able to set the draft.watermark.image parameter to the image > you want: > > http://docbook.sourceforge.net/release/xsl/current/doc/html/draft.watermark.image.html > Yes, that's true, but I don't think it's currently exposed in the Publican Makefile. I've been meaning to do this for a while (as well as a couple of other watermarks), so I may take a stab at a patch for Publican over the next few days. -Jared From mmcgrath at redhat.com Wed Oct 22 18:01:26 2008 From: mmcgrath at redhat.com (Mike McGrath) Date: Wed, 22 Oct 2008 13:01:26 -0500 (CDT) Subject: [publican-list] draft support? In-Reply-To: <48FF4847.3020407@redhat.com> References: <48FF4847.3020407@redhat.com> Message-ID: On Wed, 22 Oct 2008, Jonathan Robie wrote: > Mike McGrath wrote: > > Is there any way to declare a chapter book or set as a draft and have it > > get labeled as such when its built? I've seen draft watermarks for > > example but I'm not sure how they get added. > > > > Should be able to set the draft.watermark.image parameter to the image you > want: > > http://docbook.sourceforge.net/release/xsl/current/doc/html/draft.watermark.image.html > > Publican seems to come with a bunch of watermark images: > > http://docbook.sourceforge.net/release/xsl/current/doc/html/draft.watermark.image.html > > Hope this helps! > Awesome, I think thats exactly what I want. One question though (noob warning) where do I put tags? I've tried in my as well as just after my tag. I get errors either way. -Mike From jfearn at redhat.com Wed Oct 22 22:10:17 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Thu, 23 Oct 2008 08:10:17 +1000 Subject: [publican-list] draft support? In-Reply-To: References: Message-ID: <48FFA4C9.1000804@redhat.com> Mike McGrath wrote: > Is there any way to declare a chapter book or set as a draft and have it > get labeled as such when its built? I've seen draft watermarks for > example but I'm not sure how they get added. > Hi Mike, you should be able to set status to draft on a block and it should be marked up as a draft. e.g.
... I don't recall anyone ever mentioning to me that they use this, so it's either working perfectly or completely untested :) Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From mhideo at redhat.com Wed Oct 22 22:40:43 2008 From: mhideo at redhat.com (Michael Hideo-Smith) Date: Wed, 22 Oct 2008 18:40:43 -0400 (EDT) Subject: [publican-list] draft support? In-Reply-To: <48FFA4C9.1000804@redhat.com> Message-ID: <282361500.2560271224715243135.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> ----- "Jeff Fearn" wrote: > From: "Jeff Fearn" > To: "Mike McGrath" > Cc: publican-list at redhat.com > Sent: Thursday, October 23, 2008 8:10:17 AM GMT +10:00 Brisbane > Subject: Re: [publican-list] draft support? > > Mike McGrath wrote: > > Is there any way to declare a chapter book or set as a draft and > have it > > get labeled as such when its built? I've seen draft watermarks for > > example but I'm not sure how they get added. > > > > Hi Mike, you should be able to set status to draft on a block and it > should be marked up as a draft. > > e.g.
... > > I don't recall anyone ever mentioning to me that they use this, so > it's either working perfectly or completely untested :) > been wahile since I have used this. It is useful for review purposes as you can watermark a particular section or even a para. Also, i have set the status to "alpha 1" "beta 1" watermarks etc. You can even adjust the watermarkimage so it displays a date. i have used that as a due date for a particular section or paragarph that i have needed reviewed. From jfearn at redhat.com Wed Oct 22 22:44:00 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Thu, 23 Oct 2008 08:44:00 +1000 Subject: [publican-list] draft support? In-Reply-To: <282361500.2560271224715243135.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> References: <282361500.2560271224715243135.JavaMail.root@zmail01.collab.prod.int.phx2.redhat.com> Message-ID: <48FFACB0.4090601@redhat.com> Michael Hideo-Smith wrote: > ----- "Jeff Fearn" wrote: > >> From: "Jeff Fearn" >> To: "Mike McGrath" >> Cc: publican-list at redhat.com >> Sent: Thursday, October 23, 2008 8:10:17 AM GMT +10:00 Brisbane >> Subject: Re: [publican-list] draft support? >> >> Mike McGrath wrote: >>> Is there any way to declare a chapter book or set as a draft and >> have it >>> get labeled as such when its built? I've seen draft watermarks for >>> example but I'm not sure how they get added. >>> >> Hi Mike, you should be able to set status to draft on a block and it >> should be marked up as a draft. >> >> e.g.
... >> >> I don't recall anyone ever mentioning to me that they use this, so >> it's either working perfectly or completely untested :) >> > > been wahile since I have used this. It is useful for review purposes as you can watermark a particular section or even a para. Also, i have set the status to "alpha 1" "beta 1" watermarks etc. You can even adjust the watermarkimage so it displays a date. i have used that as a due date for a particular section or paragarph that i have needed reviewed. Clearly you need to add this to the Users Guide :D Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From mmcgrath at redhat.com Thu Oct 23 03:35:45 2008 From: mmcgrath at redhat.com (Mike McGrath) Date: Wed, 22 Oct 2008 22:35:45 -0500 (CDT) Subject: [publican-list] draft support? In-Reply-To: <48FFA4C9.1000804@redhat.com> References: <48FFA4C9.1000804@redhat.com> Message-ID: On Thu, 23 Oct 2008, Jeff Fearn wrote: > Mike McGrath wrote: > > Is there any way to declare a chapter book or set as a draft and have it > > get labeled as such when its built? I've seen draft watermarks for > > example but I'm not sure how they get added. > > > > Hi Mike, you should be able to set status to draft on a block and it should be > marked up as a draft. > > e.g.
... > > I don't recall anyone ever mentioning to me that they use this, so it's either > working perfectly or completely untested :) > Don't take my word for it but I didn't notice any difference in the output with make html-all anyway. -Mike From mmcgrath at redhat.com Thu Oct 23 19:11:54 2008 From: mmcgrath at redhat.com (Mike McGrath) Date: Thu, 23 Oct 2008 14:11:54 -0500 (CDT) Subject: [publican-list] Advice please Message-ID: I hope my constant use of this list for help isn't becoming irksome. I'm having a bit of a format issue, and one I've tried a bunch of different things to correct. Take a look: http://mmcgrath.fedorapeople.org/csi/html-single/#HostIptables-Standard-Introduction-Prerequisites http://mmcgrath.fedorapeople.org/standard.xml (source) I've got a seg list generating that. I need to figure out a format to basically allow for the following fields. Complete Requirement Action Config Comment As you can see this almost works except the comment fields are generally crazy. I'd expect all the other fields to generally be short. Even the Config item is usually not very long. Even if I could get the comment section below the normal line in its own box (I just don't know how). I'm open to completely changing how I'm doing it there but my inexperience with docbook is showing through here and I'd hate to write too much more only to have more to change later. Any suggestions? -Mike From jfearn at redhat.com Thu Oct 23 21:47:35 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Fri, 24 Oct 2008 07:47:35 +1000 Subject: [publican-list] draft support? In-Reply-To: References: <48FFA4C9.1000804@redhat.com> Message-ID: <4900F0F7.4000609@redhat.com> Mike McGrath wrote: > On Thu, 23 Oct 2008, Jeff Fearn wrote: > >> Mike McGrath wrote: >>> Is there any way to declare a chapter book or set as a draft and have it >>> get labeled as such when its built? I've seen draft watermarks for >>> example but I'm not sure how they get added. >>> >> Hi Mike, you should be able to set status to draft on a block and it should be >> marked up as a draft. >> >> e.g.
... >> >> I don't recall anyone ever mentioning to me that they use this, so it's either >> working perfectly or completely untested :) >> > > Don't take my word for it but I didn't notice any difference in the output > with make html-all anyway. This is a bug as it should mark it up as draft text, please open a BZ. Cheers, jeff. From jfearn at redhat.com Thu Oct 23 22:11:13 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Fri, 24 Oct 2008 08:11:13 +1000 Subject: [publican-list] Advice please In-Reply-To: References: Message-ID: <4900F681.6040603@redhat.com> Hi Mike, Mike McGrath wrote: > I hope my constant use of this list for help isn't becoming irksome. This is what the list is for :) > I'm > having a bit of a format issue, and one I've tried a bunch of different > things to correct. > > Take a look: > > http://mmcgrath.fedorapeople.org/csi/html-single/#HostIptables-Standard-Introduction-Prerequisites > > http://mmcgrath.fedorapeople.org/standard.xml (source) > > I've got a seg list generating that. I need to figure out a format to > basically allow for the following fields. > > Complete > > Requirement > > Action > > Config > > Comment > > > As you can see this almost works except the comment fields are generally > crazy. I'd expect all the other fields to generally be short. Even the > Config item is usually not very long. Even if I could get the comment > section below the normal line in its own box (I just don't know how). > > I'm open to completely changing how I'm doing it there but my inexperience > with docbook is showing through here and I'd hate to write too much more > only to have more to change later. Any suggestions? Text in tables always causes problems, the problems increase with number of columns and text length :( command in XML becomes code in HTML, code is a verbatim tag and won't wrap. You could try changing command to userinput or parameter. We have a couple of information design people in the office, I will go poke them for you if that doesn't work :D Cheers, Jeff. From kwade at redhat.com Thu Oct 23 22:14:47 2008 From: kwade at redhat.com (Karsten 'quaid' Wade) Date: Thu, 23 Oct 2008 15:14:47 -0700 Subject: [publican-list] Advice please In-Reply-To: <4900F681.6040603@redhat.com> References: <4900F681.6040603@redhat.com> Message-ID: <1224800087.21380.400.camel@calliope.phig.org> On Fri, 2008-10-24 at 08:11 +1000, Jeff Fearn wrote: > Text in tables always causes problems, the problems increase with number of > columns and text length :( You said it, brother! Tabling is a necessary evil. > command in XML becomes code in HTML, code is a verbatim tag and won't wrap. You > could try changing command to userinput or parameter. The balance here is if you want to let those lines be broken. It would be nice to auto-insert a '\' character when certain commands are broken into multiple lines. Then you can set a column width minimum and maximum. - Karsten -- Karsten Wade, Community Gardener Dev Fu : http://developer.redhatmagazine.com Fedora : http://quaid.fedorapeople.org gpg key : AD0E0C41 -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From jfearn at redhat.com Thu Oct 23 22:42:06 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Fri, 24 Oct 2008 08:42:06 +1000 Subject: [publican-list] Advice please In-Reply-To: <1224800087.21380.400.camel@calliope.phig.org> References: <4900F681.6040603@redhat.com> <1224800087.21380.400.camel@calliope.phig.org> Message-ID: <4900FDBE.7000602@redhat.com> Karsten 'quaid' Wade wrote: > On Fri, 2008-10-24 at 08:11 +1000, Jeff Fearn wrote: > >> Text in tables always causes problems, the problems increase with number of >> columns and text length :( > > You said it, brother! Tabling is a necessary evil. > >> command in XML becomes code in HTML, code is a verbatim tag and won't wrap. You >> could try changing command to userinput or parameter. > > The balance here is if you want to let those lines be broken. It would > be nice to auto-insert a '\' character when certain commands are broken > into multiple lines. Then you can set a column width minimum and > maximum. That would require him to stop using a seglist and directly use tables, which is a fair bit of effort. Since command is often used inline it would create interesting output in some cases. Auto hyphenation of verbatim text in FOP is a dark art, most likely resulting in text that looks fine in HTML but breaks the PDF layout :( Auto Hyphenation of Latin text in non-Latin languages can cause absolutely weird output :( Cheers, Jeff. From bugzilla at redhat.com Fri Oct 24 02:13:58 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 23 Oct 2008 22:13:58 -0400 Subject: [publican-list] [Bug 468316] New: Need an online help brand in Publican. Message-ID: Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. Summary: Need an online help brand in Publican. https://bugzilla.redhat.com/show_bug.cgi?id=468316 Summary: Need an online help brand in Publican. Product: Red Hat Enterprise Linux 5 Version: 5.4 Platform: All OS/Version: Linux Status: NEW Severity: medium Priority: urgent Component: publican AssignedTo: jfearn at redhat.com ReportedBy: sburgess at redhat.com QAContact: ecs-dev-list at redhat.com CC: publican-list at redhat.com Classification: Red Hat Description of problem: Need a brand that will format online help for web applications, such as ovirt in a user-friendly fashion. Version-Release number of selected component (if applicable): How reproducible: On clicking the Help button on the web UI, the help documentation appears as html pages, in the format of a book, with a TOC, numbered chapters and sections. Steps to Reproduce: 1. Click Help button 2. Document displays in a standard "book" format. Actual results: Clicking the Help button displays document that is formatted and delivered as a book. Expected results: Clicking the Help button should display document that is formatted and delivered as online help. 1.TOC should be in the left hand frame as is currently done in for the desktop versions 2. HTML output should be chunked so as to deliver only the relevant information 3. Numbering should be removed from all section headings 4. Search and Index tags should be available in the TOC panel 5. Users should be able to search from within the TOC panel 6. Every page should have the navigation buttons 7. Document Conventions should be removed from the Common Content for online help. 8. Open in its own browser window with virtually no chrome. 9. Help window should be resizable, but with a fixed minimum width 10.User should be able to can view both the app and the help at the same time. Additional info: -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From kwade at redhat.com Fri Oct 24 02:31:19 2008 From: kwade at redhat.com (Karsten 'quaid' Wade) Date: Thu, 23 Oct 2008 19:31:19 -0700 Subject: [publican-list] Advice please In-Reply-To: <4900FDBE.7000602@redhat.com> References: <4900F681.6040603@redhat.com> <1224800087.21380.400.camel@calliope.phig.org> <4900FDBE.7000602@redhat.com> Message-ID: <1224815479.21380.420.camel@calliope.phig.org> On Fri, 2008-10-24 at 08:42 +1000, Jeff Fearn wrote: > Karsten 'quaid' Wade wrote: > > > > The balance here is if you want to let those lines be broken. It would > > be nice to auto-insert a '\' character when certain commands are broken > > into multiple lines. Then you can set a column width minimum and > > maximum. > > That would require him to stop using a seglist and directly use tables, which is a > fair bit of effort. I was thinking of it as seglist and doing the fixed width in the CSS. Since it is output to a table in HTML and FO, I was hoping we'd have a chance to insert something. It would require an ID tag of some kind for the styling to pick up. Right there is where my knowledge ends and you understand better. :) > Since command is often used inline it would create interesting output > in some cases. > > Auto hyphenation of verbatim text in FOP is a dark art, most likely > resulting in > text that looks fine in HTML but breaks the PDF layout :( > > Auto Hyphenation of Latin text in non-Latin languages can cause > absolutely weird > output :( I see what you mean. It might be that Mike needs to move to a different construct, or use a different tabling style. The goal is for visual parsing by humans, right? That is, you aren't trying to use a table in the database sense, correct? I'm thinking of stuff such as column and row spanning. - Karsten -- Karsten Wade, Community Gardener Dev Fu : http://developer.redhatmagazine.com Fedora : http://quaid.fedorapeople.org gpg key : AD0E0C41 -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 189 bytes Desc: This is a digitally signed message part URL: From bugzilla at redhat.com Fri Oct 24 02:28:20 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 23 Oct 2008 22:28:20 -0400 Subject: [publican-list] [Bug 468316] RFE: Need an online help brand in Publican. In-Reply-To: References: Message-ID: <200810240228.m9O2SKhB007527@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=468316 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |kbaker at redhat.com AssignedTo|jfearn at redhat.com |mhideo at redhat.com Summary|Need an online help brand |RFE: Need an online help |in Publican. |brand in Publican. --- Comment #1 from Jeff Fearn 2008-10-23 22:28:19 EDT --- This would take approximately 2 to 3 weeks of dedicated effort to achieve. The idea is, IMHO, deeply flawed. Assigning to mhideo for assessment. Mike, if you want this done you will need to clear the time allocation with kbaker. Added Kev to CC. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From mmcgrath at redhat.com Fri Oct 24 13:47:16 2008 From: mmcgrath at redhat.com (Mike McGrath) Date: Fri, 24 Oct 2008 08:47:16 -0500 (CDT) Subject: [publican-list] Advice please In-Reply-To: <1224815479.21380.420.camel@calliope.phig.org> References: <4900F681.6040603@redhat.com> <1224800087.21380.400.camel@calliope.phig.org> <4900FDBE.7000602@redhat.com> <1224815479.21380.420.camel@calliope.phig.org> Message-ID: On Thu, 23 Oct 2008, Karsten 'quaid' Wade wrote: > > It might be that Mike needs to move to a different construct, or use a > different tabling style. The goal is for visual parsing by humans, > right? That is, you aren't trying to use a table in the database sense, > correct? > > I'm thinking of stuff such as column and row spanning. > The goal is visual parsing by humans. Ideally it will look like something that people can print up, easily scan for each item and check it off as done. I've been looking a bit at variable lists too though it seems each varlistentry can only have one list item. -Mike From bugzilla at redhat.com Fri Oct 24 15:29:28 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 24 Oct 2008 11:29:28 -0400 Subject: [publican-list] [Bug 468316] RFE: Need an online help brand in Publican. In-Reply-To: References: Message-ID: <200810241529.m9OFTS0q012104@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=468316 Kevin Baker changed: What |Removed |Added ---------------------------------------------------------------------------- Group| |devel -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From mmcallis at redhat.com Fri Oct 24 22:53:16 2008 From: mmcallis at redhat.com (Murray McAllister) Date: Sat, 25 Oct 2008 08:53:16 +1000 Subject: [publican-list] Advice please In-Reply-To: References: <4900F681.6040603@redhat.com> <1224800087.21380.400.camel@calliope.phig.org> <4900FDBE.7000602@redhat.com> <1224815479.21380.420.camel@calliope.phig.org> Message-ID: <490251DC.1080405@redhat.com> Mike McGrath wrote: > On Thu, 23 Oct 2008, Karsten 'quaid' Wade wrote: >> It might be that Mike needs to move to a different construct, or use a >> different tabling style. The goal is for visual parsing by humans, >> right? That is, you aren't trying to use a table in the database sense, >> correct? >> >> I'm thinking of stuff such as column and row spanning. >> > > The goal is visual parsing by humans. Ideally it will look like something > that people can print up, easily scan for each item and check it off as > done. I've been looking a bit at variable lists too though it seems each > varlistentry can only have one list item. > > -Mike > I'm not a design person, so this might be totally wrong. If you want to check things off, you could try an orderedlist inside a variabelist: This is a varlist term Item 1 Item 2 When built it looks as such: This is a varlist term 1. Item 1 2. Item 2 If you wanted more than one listitem, you can use an itemizedlist, but this places a ">>" point next to each one. You can override what is used with "itemizedlist mark=", but I couldn't figure out how to make the mark disappear. "An ItemizedList is a list in which every item is marked with a bullet, dash, or other dingbat, or no mark at all."[1], so I guess it is possible. Good luck! [1] From bugzilla at redhat.com Mon Oct 27 00:02:26 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Sun, 26 Oct 2008 20:02:26 -0400 Subject: [publican-list] [Bug 468316] RFE: Need an online help brand in Publican. In-Reply-To: References: Message-ID: <200810270002.m9R02QSN013016@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=468316 David O'Brien changed: What |Removed |Added ---------------------------------------------------------------------------- CC| |daobrien at redhat.com -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From ryanlerch at gmail.com Mon Oct 27 06:49:54 2008 From: ryanlerch at gmail.com (ryan lerch) Date: Mon, 27 Oct 2008 16:49:54 +1000 Subject: [publican-list] unknown publican error Message-ID: <671a617b0810262349g3e69ff00l27354852a45e637f@mail.gmail.com> Hi all, i encountered this error when trying to build a book, and was just wondering if anyone else has, and knows how to fix it: Can't call method "look_down" on an undefined value at /usr/bin/xmlClean line 968. make: *** [xml-en-US] Error 4 i am using a publican that i built myself from source (publican-0.38-0.t2.fc9.noarch) cheers, ryanlerch -------------- next part -------------- An HTML attachment was scrubbed... URL: From jfearn at redhat.com Mon Oct 27 23:20:02 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Tue, 28 Oct 2008 09:20:02 +1000 Subject: [publican-list] unknown publican error In-Reply-To: <671a617b0810262349g3e69ff00l27354852a45e637f@mail.gmail.com> References: <671a617b0810262349g3e69ff00l27354852a45e637f@mail.gmail.com> Message-ID: <49064CA2.7010702@redhat.com> ryan lerch wrote: > Hi all, > > i encountered this error when trying to build a book, and was just > wondering if anyone else has, and knows how to fix it: > > Can't call method "look_down" on an undefined value at /usr/bin/xmlClean > line 968. > make: *** [xml-en-US] Error 4 > > i am using a publican that i built myself from source > (publican-0.38-0.t2.fc9.noarch) This looks to be a side affect by the new column counting routine, see BZ 462205. It looks like either your tgroup is not in a table, or your doc is structured in a way that the table can not be accessed when processing this file. Please open a bug with the location of the offending file and I'll figure out a way of gracefully failing. Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From bugzilla at redhat.com Tue Oct 28 03:45:32 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Mon, 27 Oct 2008 23:45:32 -0400 Subject: [publican-list] [Bug 468789] build error from xmlclean when trying to build the installation guide In-Reply-To: References: Message-ID: <200810280345.m9S3jWLH009996@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=468789 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |CLOSED Fixed In Version| |0.39 Resolution| |CURRENTRELEASE --- Comment #1 from Jeff Fearn 2008-10-27 23:45:31 EDT --- Added check for failure to find table, output non-fatal warning. Sample Output: Graphical_Installation_x86_ppc-table-1-tgroup.xml *WARNING: table validation failed* Could not determine table for tgroup, column numbers can not be validated at /usr/bin/xmlClean line 969. Graphical_Installation_x86_ppc-table-1-title.xml -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From jfearn at redhat.com Tue Oct 28 07:12:41 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Tue, 28 Oct 2008 17:12:41 +1000 Subject: [publican-list] Oddities with draft settings Message-ID: <4906BB69.3020100@redhat.com> Hi ho, I have been taking a look at drafting due to https://bugzilla.redhat.com/show_bug.cgi?id=468305 and there is some crazy stuff happening in the default DocBook XSL. In HTML you can only get the draft image in the background in the root node for the current page and everything on that page is marked as draft. In html-single you have to set status to draft in the book and everything in the book is marked. In html the node it will take affect in depends on whether on not that block is on it's own page. In PDF you can only set draft at book or chapter levels. I've had a look at the XSL and it's possible to get the HTML outputs to behave as you'd expect, switch ON at the book/chapter/section level regardless of it's position on the page. However the PDF is a different story, it may not be possible to imitate this behaviour without rewriting a large quantity of the default XSL. How should we handle this? I'm tempted to leave the PDF in it's current state and make the HTML outputs work properly. While this would make drafting with the PDF less manageable than drafting with the HTML, it will mean drafting gets fixed in the HTML a lot sooner. Also I have been asked to add other status' to allow documentation to be marked as beta/alpha/RC etc, this is easy in the HTML but requires the same rewrite as for the beta status in the PDF. All comments welcome. Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From ryanlerch at gmail.com Tue Oct 28 08:13:19 2008 From: ryanlerch at gmail.com (ryan lerch) Date: Tue, 28 Oct 2008 18:13:19 +1000 Subject: [publican-list] Oddities with draft settings In-Reply-To: <4906BB69.3020100@redhat.com> References: <4906BB69.3020100@redhat.com> Message-ID: <671a617b0810280113u79b25a3ar864ee11758f9737a@mail.gmail.com> as long as the watermark is #ff00ff, i am happy. cheers, ryanlerch On Tue, Oct 28, 2008 at 5:12 PM, Jeff Fearn wrote: > Hi ho, I have been taking a look at drafting due to > https://bugzilla.redhat.com/show_bug.cgi?id=468305 and there is some crazy > stuff happening in the default DocBook XSL. > > In HTML you can only get the draft image in the background in the root node > for the current page and everything on that page is marked as draft. > > In html-single you have to set status to draft in the book and everything > in the book is marked. > > In html the node it will take affect in depends on whether on not that > block is on it's own page. > > In PDF you can only set draft at book or chapter levels. > > I've had a look at the XSL and it's possible to get the HTML outputs to > behave as you'd expect, switch ON at the book/chapter/section level > regardless of it's position on the page. However the PDF is a different > story, it may not be possible to imitate this behaviour without rewriting a > large quantity of the default XSL. > > How should we handle this? I'm tempted to leave the PDF in it's current > state and make the HTML outputs work properly. While this would make > drafting with the PDF less manageable than drafting with the HTML, it will > mean drafting gets fixed in the HTML a lot sooner. > > Also I have been asked to add other status' to allow documentation to be > marked as beta/alpha/RC etc, this is easy in the HTML but requires the same > rewrite as for the beta status in the PDF. > > All comments welcome. > > Cheers, Jeff. > > -- > Jeff Fearn > Software Engineer > Engineering Operations > Red Hat, Inc > Freedom ... courage ... Commitment ... ACCOUNTABILITY > > _______________________________________________ > publican-list mailing list > publican-list at redhat.com > https://www.redhat.com/mailman/listinfo/publican-list > Wiki: https://fedorahosted.org/publican > -------------- next part -------------- An HTML attachment was scrubbed... URL: From jfearn at redhat.com Tue Oct 28 23:45:44 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Wed, 29 Oct 2008 09:45:44 +1000 Subject: [publican-list] Commit access to repo policy? Message-ID: <4907A428.8030701@redhat.com> Hi, we currently don't have a policy for granting commit access to the svn repo, it's probably about time we had one. Does anyone have any idea what such a policy should entail? Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From bugzilla at redhat.com Wed Oct 29 01:20:39 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 28 Oct 2008 21:20:39 -0400 Subject: [publican-list] [Bug 442969] FEATURE REQUEST: docbook-lint In-Reply-To: References: Message-ID: <200810290120.m9T1KdCb020451@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=442969 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|ASSIGNED |CLOSED CC| |jfearn at redhat.com Resolution| |DEFERRED -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 29 01:57:34 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 28 Oct 2008 21:57:34 -0400 Subject: [publican-list] [Bug 467654] corners missing on when it contains or In-Reply-To: References: Message-ID: <200810290157.m9T1vY4N026312@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=467654 --- Comment #3 from Jeff Fearn 2008-10-28 21:57:34 EDT --- Right margin was being overridden for verbatim and admonitions. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 29 01:56:57 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 28 Oct 2008 21:56:57 -0400 Subject: [publican-list] [Bug 467654] corners missing on when it contains or In-Reply-To: References: Message-ID: <200810290156.m9T1uvDk026227@bz-web2.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=467654 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Status|NEW |CLOSED Fixed In Version| |0.39 Resolution| |WORKSFORME -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Wed Oct 29 03:28:04 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Tue, 28 Oct 2008 23:28:04 -0400 Subject: [publican-list] [Bug 467654] corners missing on when it contains or In-Reply-To: References: Message-ID: <200810290328.m9T3S4so000801@bz-web1.app.phx.redhat.com> Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. https://bugzilla.redhat.com/show_bug.cgi?id=467654 Jeff Fearn changed: What |Removed |Added ---------------------------------------------------------------------------- Resolution|WORKSFORME |CURRENTRELEASE -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From mmcallis at redhat.com Thu Oct 30 03:34:23 2008 From: mmcallis at redhat.com (Murray McAllister) Date: Thu, 30 Oct 2008 13:34:23 +1000 Subject: [publican-list] Commit access to repo policy? In-Reply-To: <4907A428.8030701@redhat.com> References: <4907A428.8030701@redhat.com> Message-ID: <49092B3F.2050308@redhat.com> Jeff Fearn wrote: > Hi, we currently don't have a policy for granting commit access to the > svn repo, it's probably about time we had one. > > Does anyone have any idea what such a policy should entail? > > Cheers, Jeff. > Maybe submitting 5-10 patches via Bugzilla? From lbrindle at redhat.com Thu Oct 30 03:37:44 2008 From: lbrindle at redhat.com (Lana Brindley) Date: Thu, 30 Oct 2008 14:37:44 +1100 Subject: [publican-list] Commit access to repo policy? In-Reply-To: <49092B3F.2050308@redhat.com> References: <4907A428.8030701@redhat.com> <49092B3F.2050308@redhat.com> Message-ID: <49092C08.3090907@redhat.com> Murray McAllister wrote: > Jeff Fearn wrote: >> Hi, we currently don't have a policy for granting commit access to the >> svn repo, it's probably about time we had one. >> >> Does anyone have any idea what such a policy should entail? >> >> Cheers, Jeff. >> > Maybe submitting 5-10 patches via Bugzilla? > I think that's a great theory. Once they've proven they can submit something useful to the documentation, let them have at it, I say! L -------------- next part -------------- A non-text attachment was scrubbed... Name: lbrindle.vcf Type: text/x-vcard Size: 976 bytes Desc: not available URL: From mmcallis at redhat.com Thu Oct 30 04:30:16 2008 From: mmcallis at redhat.com (Murray McAllister) Date: Thu, 30 Oct 2008 14:30:16 +1000 Subject: [publican-list] Commit access to repo policy? In-Reply-To: <49092C08.3090907@redhat.com> References: <4907A428.8030701@redhat.com> <49092B3F.2050308@redhat.com> <49092C08.3090907@redhat.com> Message-ID: <49093858.9060106@redhat.com> Lana Brindley wrote: > Murray McAllister wrote: >> Jeff Fearn wrote: >>> Hi, we currently don't have a policy for granting commit access to >>> the svn repo, it's probably about time we had one. >>> >>> Does anyone have any idea what such a policy should entail? >>> >>> Cheers, Jeff. >>> >> Maybe submitting 5-10 patches via Bugzilla? >> > > I think that's a great theory. Once they've proven they can submit > something useful to the documentation, let them have at it, I say! > > L > I stole the idea from mhideo From jfearn at redhat.com Thu Oct 30 05:10:59 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Thu, 30 Oct 2008 15:10:59 +1000 Subject: [publican-list] Commit access to repo policy? In-Reply-To: <49092C08.3090907@redhat.com> References: <4907A428.8030701@redhat.com> <49092B3F.2050308@redhat.com> <49092C08.3090907@redhat.com> Message-ID: <490941E3.9090500@redhat.com> Lana Brindley wrote: > Murray McAllister wrote: >> Jeff Fearn wrote: >>> Hi, we currently don't have a policy for granting commit access to >>> the svn repo, it's probably about time we had one. >>> >>> Does anyone have any idea what such a policy should entail? >>> >>> Cheers, Jeff. >>> >> Maybe submitting 5-10 patches via Bugzilla? >> > > I think that's a great theory. Once they've proven they can submit > something useful to the documentation, let them have at it, I say! ummm there isn't much documentation in publican, it's mostly Makefiles, XSL and perl :) Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From ccurran at redhat.com Thu Oct 30 05:36:24 2008 From: ccurran at redhat.com (Christopher Curran) Date: Thu, 30 Oct 2008 15:36:24 +1000 Subject: [publican-list] Comments in XML files, good, bad, or ugly?] In-Reply-To: <48F6562C.6040706@redhat.com> References: <48F6562C.6040706@redhat.com> Message-ID: <490947D8.5090706@redhat.com> Douglas Silas Hensley wrote: > Hi, > > I'm definitely an advocate for retaining comments, which are > obviously useful. Anything that helps the writers should be retained. > > And I disagree that we're just writers and shouldn't be doing > "coding/programming" :-) I know that I am, along with others, trying > to write modular documentation with little duplication, because I > don't want to have the same content in multiple places that will > have to be updated separately in the future. Comments, for me, are a > way to keep track, at the site, of what's going on and how I've > structured the documentation, among other uses. > > Also, I can comment in OpenOffice, so that's not a function that's > just relegated to coding (apologies if I have asserted something not > accurate here). > > Also, maven-jdocbook shows the text of by default, which > could throw someone for a loop. I'm sure you can turn that off as > well (not that finding out how will be easy), but I don't see the > point of using for comments ( could be reserved > for other useful purposes). > > And you might not miss something until it's gone... (plus, it truly > can be useful for editors, even non-vim ones) > > +1 pro-comment > > +1 for comments No one writes self documenting anything. Nuf said. > Cheers, > > Silas > > Lana Brindley wrote: > >> Jeff Fearn wrote: >> >>> Currently when you run `make clean_ids` any comments using the format get removed. >>> >>> This was left in place as in some circumstances inline comments break >>> translations as the merging process does not match the msgid. >>> Is removing the comments the correct behaviour? >>> >>> I have no strong feelings on the subject and it is a fairly simple fix >>> from publicans perspective. The translation issue is a problem with >>> either po2xml or msgmerge and would need to be fixed upstream, assuing >>> it hasn't already been fixed. >>> >>> Cheers, Jeff. >>> >>> >> Oh, are we re-opening this old argument discussion?? >> >> I was originally an advocate for keeping comments, this was because I >> lost a chunk of data through the make clean_ids behaviour, and got a >> little ... errr ... annoyed ;-) >> >> That said, over time (and with a bit of mellowing) it doesn't seem to me >> to be such a bad thing after all. The point has been raised that >> commenting is a standard function of any code, but the fact remains >> that, while we do indeed use a programming language (of sorts) to write >> our books, what we're doing is not coding, it's writing. We simply use >> the tags to define what our books look like (not how the books perform >> tasks, or complete functions, as does a program). >> >> Do comments belong in books? They certainly have their uses - we can use >> them to leave notes for ourselves (and any reviewers who prefer to >> review the source, rather than the output - whoever they are), but this >> can also be achieved through - the behaviour of which has >> changed now so that it doesn't print, which is great. >> >> What else are comments good for? Is there anything that can be achieved >> with comments that _can't_ be achieved through the use of another tag >> (like )? >> >> I personally can't find any good reason to keep them in, despite my best >> efforts. Perhaps that's just because I'm used to the behaviour now, and >> it's a case of better the devil you know? If anyone can come up with a >> compelling reason for changing the behaviour, I'd like to hear it :) >> >> L >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican >> > > From jfearn at redhat.com Thu Oct 30 05:41:38 2008 From: jfearn at redhat.com (Jeff Fearn) Date: Thu, 30 Oct 2008 15:41:38 +1000 Subject: [publican-list] Comments in XML files, good, bad, or ugly?] In-Reply-To: <490947D8.5090706@redhat.com> References: <48F6562C.6040706@redhat.com> <490947D8.5090706@redhat.com> Message-ID: <49094912.8090300@redhat.com> Christopher Curran wrote: > +1 for comments > No one writes self documenting anything. Nuf said. Just so everyone is aware clean_ids was modified in 0.38 to retain comments. Cheers, Jeff. -- Jeff Fearn Software Engineer Engineering Operations Red Hat, Inc Freedom ... courage ... Commitment ... ACCOUNTABILITY From ccurran at redhat.com Thu Oct 30 06:47:30 2008 From: ccurran at redhat.com (Christopher Curran) Date: Thu, 30 Oct 2008 16:47:30 +1000 Subject: [publican-list] Comments in XML files, good, bad, or ugly?] In-Reply-To: <49094912.2070807@redhat.com> References: <48F6562C.6040706@redhat.com> <490947D8.5090706@redhat.com> <49094912.2070807@redhat.com> Message-ID: <49095882.6010508@redhat.com> Murray McAllister wrote: > Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > > Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > > Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > > Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > > Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > > Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > > Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > > Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > > Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > > Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > > Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > > Christopher Curran wrote: >> Douglas Silas Hensley wrote: >>> Hi, >>> >>> I'm definitely an advocate for retaining comments, which are >>> obviously useful. Anything that helps the writers should be retained. >>> >>> And I disagree that we're just writers and shouldn't be doing >>> "coding/programming" :-) I know that I am, along with others, trying >>> to write modular documentation with little duplication, because I >>> don't want to have the same content in multiple places that will >>> have to be updated separately in the future. Comments, for me, are a >>> way to keep track, at the site, of what's going on and how I've >>> structured the documentation, among other uses. >>> >>> Also, I can comment in OpenOffice, so that's not a function that's >>> just relegated to coding (apologies if I have asserted something not >>> accurate here). >>> >>> Also, maven-jdocbook shows the text of by default, which >>> could throw someone for a loop. I'm sure you can turn that off as >>> well (not that finding out how will be easy), but I don't see the >>> point of using for comments ( could be reserved >>> for other useful purposes). >>> >>> And you might not miss something until it's gone... (plus, it truly >>> can be useful for editors, even non-vim ones) >>> >>> +1 pro-comment >>> >>> >> +1 for comments >> No one writes self documenting anything. Nuf said. >> >>> Cheers, >>> >>> Silas >>> >>> Lana Brindley wrote: >>> >>>> Jeff Fearn wrote: >>>> >>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>> >>>>> This was left in place as in some circumstances inline comments break >>>>> translations as the merging process does not match the msgid. >>>>> Is removing the comments the correct behaviour? >>>>> >>>>> I have no strong feelings on the subject and it is a fairly simple >>>>> fix >>>>> from publicans perspective. The translation issue is a problem with >>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>> assuing >>>>> it hasn't already been fixed. >>>>> >>>>> Cheers, Jeff. >>>>> >>>>> >>>> Oh, are we re-opening this old argument discussion?? >>>> >>>> I was originally an advocate for keeping comments, this was because I >>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>> little ... errr ... annoyed ;-) >>>> >>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>> to me >>>> to be such a bad thing after all. The point has been raised that >>>> commenting is a standard function of any code, but the fact remains >>>> that, while we do indeed use a programming language (of sorts) to >>>> write >>>> our books, what we're doing is not coding, it's writing. We simply use >>>> the tags to define what our books look like (not how the books perform >>>> tasks, or complete functions, as does a program). >>>> >>>> Do comments belong in books? They certainly have their uses - we >>>> can use >>>> them to leave notes for ourselves (and any reviewers who prefer to >>>> review the source, rather than the output - whoever they are), but >>>> this >>>> can also be achieved through - the behaviour of which has >>>> changed now so that it doesn't print, which is great. >>>> >>>> What else are comments good for? Is there anything that can be >>>> achieved >>>> with comments that _can't_ be achieved through the use of another tag >>>> (like )? >>>> >>>> I personally can't find any good reason to keep them in, despite my >>>> best >>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>> and >>>> it's a case of better the devil you know? If anyone can come up with a >>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>> >>>> L >>>> >>>> _______________________________________________ >>>> publican-list mailing list >>>> publican-list at redhat.com >>>> https://www.redhat.com/mailman/listinfo/publican-list >>>> Wiki: https://fedorahosted.org/publican >>>> >>> >>> >> >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican > > > Trimming posts takes too much effort. >> _______________________________________________ >> publican-list mailing list >> publican-list at redhat.com >> https://www.redhat.com/mailman/listinfo/publican-list >> Wiki: https://fedorahosted.org/publican I thought I could almost hear something off-list. Chris From ccurran at redhat.com Thu Oct 30 06:51:31 2008 From: ccurran at redhat.com (Christopher Curran) Date: Thu, 30 Oct 2008 16:51:31 +1000 Subject: [publican-list] Comments in XML files, good, bad, or ugly?] In-Reply-To: <49094912.8090300@redhat.com> References: <48F6562C.6040706@redhat.com> <490947D8.5090706@redhat.com> <49094912.8090300@redhat.com> Message-ID: <49095973.1070401@redhat.com> Jeff Fearn wrote: > Christopher Curran wrote: >> +1 for comments >> No one writes self documenting anything. Nuf said. > > Just so everyone is aware clean_ids was modified in 0.38 to retain > comments. > > Cheers, Jeff. > Thread is moot. To the rawhide package repository. From mmcallis at redhat.com Thu Oct 30 06:54:45 2008 From: mmcallis at redhat.com (Murray McAllister) Date: Thu, 30 Oct 2008 16:54:45 +1000 Subject: [publican-list] Comments in XML files, good, bad, or ugly?] In-Reply-To: <49095882.6010508@redhat.com> References: <48F6562C.6040706@redhat.com> <490947D8.5090706@redhat.com> <49094912.2070807@redhat.com> <49095882.6010508@redhat.com> Message-ID: <49095A35.2080706@redhat.com> Christopher Curran wrote: > Murray McAllister wrote: >> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican >> >> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican >> >> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican >> >> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican >> >> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican >> >> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican >> >> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican >> >> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican >> >> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican >> >> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican >> >> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican >> >> Christopher Curran wrote: >>> Douglas Silas Hensley wrote: >>>> Hi, >>>> >>>> I'm definitely an advocate for retaining comments, which are >>>> obviously useful. Anything that helps the writers should be retained. >>>> >>>> And I disagree that we're just writers and shouldn't be doing >>>> "coding/programming" :-) I know that I am, along with others, trying >>>> to write modular documentation with little duplication, because I >>>> don't want to have the same content in multiple places that will >>>> have to be updated separately in the future. Comments, for me, are a >>>> way to keep track, at the site, of what's going on and how I've >>>> structured the documentation, among other uses. >>>> >>>> Also, I can comment in OpenOffice, so that's not a function that's >>>> just relegated to coding (apologies if I have asserted something not >>>> accurate here). >>>> >>>> Also, maven-jdocbook shows the text of by default, which >>>> could throw someone for a loop. I'm sure you can turn that off as >>>> well (not that finding out how will be easy), but I don't see the >>>> point of using for comments ( could be reserved >>>> for other useful purposes). >>>> >>>> And you might not miss something until it's gone... (plus, it truly >>>> can be useful for editors, even non-vim ones) >>>> >>>> +1 pro-comment >>>> >>>> >>> +1 for comments >>> No one writes self documenting anything. Nuf said. >>> >>>> Cheers, >>>> >>>> Silas >>>> >>>> Lana Brindley wrote: >>>> >>>>> Jeff Fearn wrote: >>>>> >>>>>> Currently when you run `make clean_ids` any comments using the format get removed. >>>>>> >>>>>> This was left in place as in some circumstances inline comments break >>>>>> translations as the merging process does not match the msgid. >>>>>> Is removing the comments the correct behaviour? >>>>>> >>>>>> I have no strong feelings on the subject and it is a fairly simple >>>>>> fix >>>>>> from publicans perspective. The translation issue is a problem with >>>>>> either po2xml or msgmerge and would need to be fixed upstream, >>>>>> assuing >>>>>> it hasn't already been fixed. >>>>>> >>>>>> Cheers, Jeff. >>>>>> >>>>>> >>>>> Oh, are we re-opening this old argument discussion?? >>>>> >>>>> I was originally an advocate for keeping comments, this was because I >>>>> lost a chunk of data through the make clean_ids behaviour, and got a >>>>> little ... errr ... annoyed ;-) >>>>> >>>>> That said, over time (and with a bit of mellowing) it doesn't seem >>>>> to me >>>>> to be such a bad thing after all. The point has been raised that >>>>> commenting is a standard function of any code, but the fact remains >>>>> that, while we do indeed use a programming language (of sorts) to >>>>> write >>>>> our books, what we're doing is not coding, it's writing. We simply use >>>>> the tags to define what our books look like (not how the books perform >>>>> tasks, or complete functions, as does a program). >>>>> >>>>> Do comments belong in books? They certainly have their uses - we >>>>> can use >>>>> them to leave notes for ourselves (and any reviewers who prefer to >>>>> review the source, rather than the output - whoever they are), but >>>>> this >>>>> can also be achieved through - the behaviour of which has >>>>> changed now so that it doesn't print, which is great. >>>>> >>>>> What else are comments good for? Is there anything that can be >>>>> achieved >>>>> with comments that _can't_ be achieved through the use of another tag >>>>> (like )? >>>>> >>>>> I personally can't find any good reason to keep them in, despite my >>>>> best >>>>> efforts. Perhaps that's just because I'm used to the behaviour now, >>>>> and >>>>> it's a case of better the devil you know? If anyone can come up with a >>>>> compelling reason for changing the behaviour, I'd like to hear it :) >>>>> >>>>> L >>>>> >>>>> _______________________________________________ >>>>> publican-list mailing list >>>>> publican-list at redhat.com >>>>> https://www.redhat.com/mailman/listinfo/publican-list >>>>> Wiki: https://fedorahosted.org/publican >>>>> >>>> >>>> >>> >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican >> >> >> Trimming posts takes too much effort. >>> _______________________________________________ >>> publican-list mailing list >>> publican-list at redhat.com >>> https://www.redhat.com/mailman/listinfo/publican-list >>> Wiki: https://fedorahosted.org/publican > I thought I could almost hear something off-list. > > Chris > pwned! ;) From bugzilla at redhat.com Fri Oct 31 03:26:22 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Thu, 30 Oct 2008 23:26:22 -0400 Subject: [publican-list] [Bug 469286] New: screen inside para outputs invalid XHTML Message-ID: Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. Summary: screen inside para outputs invalid XHTML https://bugzilla.redhat.com/show_bug.cgi?id=469286 Summary: screen inside para outputs invalid XHTML Product: Red Hat Enterprise Linux 5 Version: 5.2 Platform: All OS/Version: Linux Status: NEW Severity: medium Priority: urgent Component: publican AssignedTo: jfearn at redhat.com ReportedBy: jfearn at redhat.com QAContact: ecs-dev-list at redhat.com CC: publican-list at redhat.com Classification: Red Hat Description of problem: All publican output should be XHTML 1.0 strict compliant. Nesting a screen in a para, which is legal DocBook, outputs invalid XHTML. Version-Release number of selected component (if applicable): 0.38 How reproducible: Always Steps to Reproduce: 1. Nest a screen in a para 2. make html-single-en-US 3. xmllint --valid --noout tmp/en-US/html-single/index.html Actual results: index.html:226: element p: validity error : Element pre is not declared in p list of possible children Expected results: no errors Additional info: In XHTML p is only permitted to include inline items. In DocBook para is permitted to contain block level tags. Consider switching p output to
as div is allowed to contain block level elements. Consider running xmllint over Users_Guide when building publican-docs package. It would be neat to have a big book of DocBook examples that we could use to test all possible combinations of DocBook tags. -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug. From bugzilla at redhat.com Fri Oct 31 05:20:43 2008 From: bugzilla at redhat.com (bugzilla at redhat.com) Date: Fri, 31 Oct 2008 01:20:43 -0400 Subject: [publican-list] [Bug 469298] New: RFE: Improve support for tags Message-ID: Please do not reply directly to this email. All additional comments should be made in the comments box of this bug. Summary: RFE: Improve support for tags https://bugzilla.redhat.com/show_bug.cgi?id=469298 Summary: RFE: Improve support for tags Product: Red Hat Enterprise Linux 5 Version: 5.2 Platform: All OS/Version: Linux Status: NEW Severity: medium Priority: medium Component: publican AssignedTo: jfearn at redhat.com ReportedBy: daobrien at redhat.com QAContact: ecs-dev-list at redhat.com CC: publican-list at redhat.com Classification: Red Hat Description of problem: publican does not fail if or child tags are included, but there is no appropriate formatting, something similar to , perhaps. Version-Release number of selected component (if applicable): rpm -qi publican Name : publican Relocations: (not relocatable) Version : 0.38 Vendor: Red Hat, Inc. Release : 0.el5 Build Date: Thu 16 Oct 2008 02:36:59 PM EST How reproducible: always Steps to Reproduce: 1. 2. 3. Actual results: output appears to be left-justified and plain text is centered Expected results: Similar to etc? Additional info: -- Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are on the CC list for the bug.