I've attempted to determine some information about the callout images used in fedora's documentation --- to no avail.
So I bow to the mercy of the mailinglist and ask for help. What is the standardized styling and location of the callout images? I have built custom callouts for current development of my xml sources; but didn't want to stray from standard practice.
Also I came across a peculiar problem declaring the xsl parameter using xmlto. For some reason due to the java implemented processor, I am getting a ColumnWidth error. The only alteration performed was to include an extension stylesheet for the declaration of a new image path. :-(
Admittedly, I have never used xmlto and prefer xsltproc. However it might be a moot point if the standard path is acceptable.
Thanks, Thomas
Thomas Jones wrote:
I've attempted to determine some information about the callout images used in fedora's documentation --- to no avail.
So I bow to the mercy of the mailinglist and ask for help. What is the standardized styling and location of the callout images? I have built custom callouts for current development of my xml sources; but didn't want to stray from standard practice.
Also I came across a peculiar problem declaring the xsl parameter using xmlto. For some reason due to the java implemented processor, I am getting a ColumnWidth error. The only alteration performed was to include an extension stylesheet for the declaration of a new image path. :-(
Admittedly, I have never used xmlto and prefer xsltproc. However it might be a moot point if the standard path is acceptable.
Thanks, Thomas
Bump.
On Mon, 2005-05-16 at 11:46 -0500, Thomas Jones wrote:
Thomas Jones wrote:
I've attempted to determine some information about the callout images used in fedora's documentation --- to no avail.
So I bow to the mercy of the mailinglist and ask for help. What is the standardized styling and location of the callout images? I have built custom callouts for current development of my xml sources; but didn't want to stray from standard practice.
Also I came across a peculiar problem declaring the xsl parameter using xmlto. For some reason due to the java implemented processor, I am getting a ColumnWidth error. The only alteration performed was to include an extension stylesheet for the declaration of a new image path. :-(
Admittedly, I have never used xmlto and prefer xsltproc. However it might be a moot point if the standard path is acceptable.
Thanks, Thomas
Bump.
I have no previous experience with callouts, other than looking at how they're used in "DocBook:TDG." My chief concern with callouts would be the impaired-reader issue. How, if at all, do callouts affect readers who, for instance, are visually impaired and use audible reader software? I would think that if there is a way to avoid callouts that does not make the document overly cumbesome, it would be wise to do so.
Can you post your sources somewhere, and post a link to the list? Perhaps then people could suggest an alternative method. If none can be found, then we should develop a standard.
I tried finding previous content in f-docs-l, but the mailing list archives are exceedingly unfriendly to searching. I searched "callout," any match on substring in any section, and *nothing* was returned. At the very least, both of Thomas' messages should have been returned. Maddening, I tell you!
Uttered "Paul W. Frields" stickster@gmail.com, spake thus:
On Mon, 2005-05-16 at 11:46 -0500, Thomas Jones wrote:
So I bow to the mercy of the mailinglist and ask for help. What is the standardized styling and location of the callout images? I have built custom callouts for current development of my xml sources; but didn't want to stray from standard practice.
I have no previous experience with callouts, other than looking at how they're used in "DocBook:TDG." My chief concern with callouts would be the impaired-reader issue. How, if at all, do callouts affect readers who, for instance, are visually impaired and use audible reader software? I would think that if there is a way to avoid callouts that does not make the document overly cumbesome, it would be wise to do so.
AFAICT, there has not been a position taken on callouts. The impaired-reader issue is best solved by adding audio content because even with text-to-audio support NONE of the pictures and such can be rendered to audio, though pehaps the <textobject> tag might be picked up. DocBook has special audio-related tags when or if we get round to making an audio translation of the material.
Perhaps we could get Garrett LeSage, who did the "stylesheet-images/" icons for us, to render some peachy-keen callout digits. If not, I could probably SVG a few.
As for the crappy archive searches: YES! My solution was to get a gmail.com account and subscribe to the list from there in addition to my "working" account on my desktop. That lets me use their nifty search tools to scan the archives.
HTH
On Mon, 2005-05-16 at 07:17 -0500, Tommy Reynolds wrote:
As for the crappy archive searches: YES! My solution was to get a gmail.com account and subscribe to the list from there in addition to my "working" account on my desktop. That lets me use their nifty search tools to scan the archives.
Unfortunately that wouldn't help with the archives that precede my Gmail account. :-( I would prefer to have the archives search actually do what it advertises! Hopefully someone @RH will have some insight into the problem. I'll tackle starting that thread when I get home today.
On Mon, 2005-05-16 at 07:17 -0500, Tommy Reynolds wrote:
AFAICT, there has not been a position taken on callouts. The impaired-reader issue is best solved by adding audio content because even with text-to-audio support NONE of the pictures and such can be rendered to audio, though pehaps the <textobject> tag might be picked up. DocBook has special audio-related tags when or if we get round to making an audio translation of the material.
We don't have a position, but they are useful when you have lots of code or the like to refer back to.
I've used them when documenting the (former) Red Hat CMS product.
Perhaps we could get Garrett LeSage, who did the "stylesheet-images/" icons for us, to render some peachy-keen callout digits. If not, I could probably SVG a few.
He actually did some up for us way back when. They look the standard callouts in /usr/share/sgml/docbook/xsl-stylesheets/images/callouts, with a soft dropshadow on them.
I'll figure out their disposition and, if possible, put them in CVS. Otherwise, Thomas can use the standard ones in the meantime.
As for the crappy archive searches: YES! My solution was to get a gmail.com account and subscribe to the list from there in addition to my "working" account on my desktop. That lets me use their nifty search tools to scan the archives.
Oh, yeah, that's what I do, sub'd to f-*-l. I also have my gmail.com account set to watch kwade@redhat.com in bugzilla.redhat.com, so now I have my own personal Google search tool. :)
- Karsten
Uttered Karsten Wade kwade@redhat.com, spake thus:
Perhaps we could get Garrett LeSage, who did the "stylesheet-images/" icons for us, to render some peachy-keen callout digits. If not, I could probably SVG a few.
He actually did some up for us way back when. They look the standard callouts in /usr/share/sgml/docbook/xsl-stylesheets/images/callouts, with a soft dropshadow on them.
Just in case, I've made some tentative callouts that you can find at
http://www.megacoder.com/callouts/
I don't pretend they're great, or even usable. They are, however, available ;-)
Cheers
Uttered Karsten Wade kwade@redhat.com, spake thus:
I'll figure out their disposition and, if possible, put them in CVS. Otherwise, Thomas can use the standard ones in the meantime.
I've gotten my callout images working well enough. They may be ugly, but they're ours(tm). I also fixed up the XSL stylesheet to pick them up out of "stylesheet-images/".
Shall I commit to CVS?
Cheers
Paul W. Frields wrote:
I have no previous experience with callouts, other than looking at how they're used in "DocBook:TDG." My chief concern with callouts would be the impaired-reader issue. How, if at all, do callouts affect readers who, for instance, are visually impaired and use audible reader software? I would think that if there is a way to avoid callouts that does not make the document overly cumbesome, it would be wise to do so.
I don't think that it is possible to retain both the visual and text element of a callout without alteration of the stylesheet.
However, it is possible to use only text callouts. i.e. |(1) and (2)
By setting the callout.graphics parameter to "0" from the makefile or a stylesheet extension. That may be an option.
Thomas |
On Mon, 2005-05-16 at 14:10 -0500, Thomas Jones wrote:
Paul W. Frields wrote:
I have no previous experience with callouts, other than looking at how they're used in "DocBook:TDG." My chief concern with callouts would be the impaired-reader issue. How, if at all, do callouts affect readers who, for instance, are visually impaired and use audible reader software? I would think that if there is a way to avoid callouts that does not make the document overly cumbesome, it would be wise to do so.
I don't think that it is possible to retain both the visual and text element of a callout without alteration of the stylesheet.
However, it is possible to use only text callouts. i.e. |(1) and (2)
By setting the callout.graphics parameter to "0" from the makefile or a stylesheet extension. That may be an option.
I've also had this happen by accident when the callouts were not in the path the stylesheet was looking for. The HTML output had text callouts, possibly from the <alt> tag. The PDF wouldn't build, of course. :)
- Karsten
I was playing with the look and feel of callout sections a few weeks back. Not only don't we have the fedora-style images, but I noticed that if you are showing command blocks that have cut'n'paste style code, the callout numbers interfere with your cut'n'paste.
I had a large enough code block that I wanted to use callout's to break it down and explain various parts ... it just killed the cut'n'pastability once added.
Thoughts?
P.S. I actually hadn't realized that docbook-style-dsssl provided stock callout images until I was about to launch this email:
$ ls /usr/share/sgml/docbook/dsssl-stylesheets-*/images/callouts/ 1.gif 10.gif 2.gif 3.gif 4.gif 5.gif 6.gif 7.gif 8.gif 9.gif
Thanks, James Laska
On Mon, 2005-05-16 at 11:46 -0500, Thomas Jones wrote:
Thomas Jones wrote:
I've attempted to determine some information about the callout images used in fedora's documentation --- to no avail.
So I bow to the mercy of the mailinglist and ask for help. What is the standardized styling and location of the callout images? I have built custom callouts for current development of my xml sources; but didn't want to stray from standard practice.
Also I came across a peculiar problem declaring the xsl parameter using xmlto. For some reason due to the java implemented processor, I am getting a ColumnWidth error. The only alteration performed was to include an extension stylesheet for the declaration of a new image path. :-(
Admittedly, I have never used xmlto and prefer xsltproc. However it might be a moot point if the standard path is acceptable.
Thanks, Thomas
Bump.
On Mon, 2005-05-16 at 13:32 -0400, James Laska wrote:
I was playing with the look and feel of callout sections a few weeks back. Not only don't we have the fedora-style images, but I noticed that if you are showing command blocks that have cut'n'paste style code, the callout numbers interfere with your cut'n'paste.
I had a large enough code block that I wanted to use callout's to break it down and explain various parts ... it just killed the cut'n'pastability once added.
Thoughts?
There's probably a rule of thumb in there somewhere, something like this:
1. If the block of code is big, try to break it down to smaller pieces 2. If that doesn't work, use callouts 3. If you are pasting the code often enough that callouts don't work, try going back to 1. 4. If all else fails, try documenting inside the actual code using comment marks. 5. If you still need callouts, try working them into the commented sections, which are less subject to change.
With 4., you can have the code the same in the source and in the docs.
Would something like that work?
- Karsten
P.S. I actually hadn't realized that docbook-style-dsssl provided stock callout images until I was about to launch this email:
$ ls /usr/share/sgml/docbook/dsssl-stylesheets-*/images/callouts/ 1.gif 10.gif 2.gif 3.gif 4.gif 5.gif 6.gif 7.gif 8.gif 9.gif
Thanks, James Laska
On Mon, 2005-05-16 at 11:46 -0500, Thomas Jones wrote:
Thomas Jones wrote:
I've attempted to determine some information about the callout images used in fedora's documentation --- to no avail.
So I bow to the mercy of the mailinglist and ask for help. What is the standardized styling and location of the callout images? I have built custom callouts for current development of my xml sources; but didn't want to stray from standard practice.
Also I came across a peculiar problem declaring the xsl parameter using xmlto. For some reason due to the java implemented processor, I am getting a ColumnWidth error. The only alteration performed was to include an extension stylesheet for the declaration of a new image path. :-(
Admittedly, I have never used xmlto and prefer xsltproc. However it might be a moot point if the standard path is acceptable.
Thanks, Thomas
Bump.
On Mon, 2005-05-16 at 10:53 -0700, Karsten Wade wrote:
On Mon, 2005-05-16 at 13:32 -0400, James Laska wrote:
I was playing with the look and feel of callout sections a few weeks back. Not only don't we have the fedora-style images, but I noticed that if you are showing command blocks that have cut'n'paste style code, the callout numbers interfere with your cut'n'paste.
I had a large enough code block that I wanted to use callout's to break it down and explain various parts ... it just killed the cut'n'pastability once added.
Thoughts?
There's probably a rule of thumb in there somewhere, something like this:
- If the block of code is big, try to break it down to smaller pieces
- If that doesn't work, use callouts
- If you are pasting the code often enough that callouts don't work,
try going back to 1. 4. If all else fails, try documenting inside the actual code using comment marks. 5. If you still need callouts, try working them into the commented sections, which are less subject to change.
With 4., you can have the code the same in the source and in the docs.
Would something like that work?
This is what I had in mind when I opined that callouts should probably be a last resort. For all the wonderful features that DocBook has, some of them are more useful as shorthand for specialized usage. There's *almost* always a better way to achieve the same end -- and better readability -- with elegant $LANG instead of cool code.