headers
Robert P. J. Day | 6 Jul 2011 14:36
Picon
Gravatar

any semantic diff between a file name and directory name?

   (not strictly a docbook question but i'm interested in the opinion  
of the gurus here.)

   i'm perusing the semantic markup of someone who has created their  
own XML language which, in all, looks fairly similar to docbook, but  
this person has explicitly defined two elements -- "file-name" and  
"directory-name" -- to be used for that respective markup.

   i'm aware that docbook has the standard "filename" element and, as  
a longtime unix/linux user, i'm well aware that directories are simply  
special cases of files and i have always marked up directory names  
with just <filename>.

   so ... would there be any compelling reason to distinguish between  
the two?  i don't have access to the XSLT so i don't know if they're  
really being treated differently and, visually at least, they're both  
just being rendered in identical monospaced font when i generate the  
HTML.

   thoughts?

rday
Permalink | Reply | 3 comments |
headers
David Cramer | 6 Jul 2011 15:02
Gravatar

Re: any semantic diff between a file name and directory name?


In DocBook this would be <filename> v. <filename class="directory">
(where the class attr can be devicefile, directory, extension,
headerfile, libraryfile, partition, orsymlink). Whether it's worth the
trouble depends on 1) how much trouble it is and 2) what you plan to do
with the information.

Personally, I've never used that distinction when processing, but you
could imagine a situation where, say, a back-of-the-book index is being
generated automatically. Maybe you want to generate a primary index
entry of "file extensions" and populate it with secondary index entries
for all the file name extensions used in the document. I've done things
like that with <database class="table"> in a schema reference where I
did automatic index generation and hyperlinking based on <database>
elements in the doc.

The wysioo editors I've used (Oxygen, XMetaL) allow you to add items to
the element list so that to the user a "filename directory" item appears
which inserts the desired markup, so the writer doesn't have to do the
work of adding an element AND an attribute.

David

On 07/06/2011 07:36 AM, Robert P. J. Day wrote:
>   (not strictly a docbook question but i'm interested in the opinion of
> the gurus here.)
> 
>   i'm perusing the semantic markup of someone who has created their own
> XML language which, in all, looks fairly similar to docbook, but this
> person has explicitly defined two elements -- "file-name" and
(Continue reading)

Permalink | Reply | 0 comments |
headers
davep | 6 Jul 2011 15:49
Picon

Re: any semantic diff between a file name and directory name?

On 07/06/2011 01:36 PM, Robert P. J. Day wrote:
>   (not strictly a docbook question but i'm interested in the opinion 
> of the gurus here.)
>
>   i'm perusing the semantic markup of someone who has created their 
> own XML language which, in all, looks fairly similar to docbook, but 
> this person has explicitly defined two elements -- "file-name" and 
> "directory-name" -- to be used for that respective markup.
>
>   i'm aware that docbook has the standard "filename" element and, as a 
> longtime unix/linux user, i'm well aware that directories are simply 
> special cases of files and i have always marked up directory names 
> with just <filename>.
>
>   so ... would there be any compelling reason to distinguish between 
> the two?  i don't have access to the XSLT so i don't know if they're 
> really being treated differently and, visually at least, they're both 
> just being rendered in identical monospaced font when i generate the HTML.

How about saying it's application dependent? If the user(s) need to 
differentiate
then two elements might be easier authoring than one element and one/two 
attributes?

Ask the users?
No real hardship to add an element?

regards

--

--
(Continue reading)

Permalink | Reply | 0 comments |
headers
rob.cavicchio | 6 Jul 2011 16:45

RE: any semantic diff between a file name and directory name?

Robert P. J. Day [mailto:rpjday <at> crashcourse.ca] wrote:

>    i'm perusing the semantic markup of someone who has created their
> own XML language which, in all, looks fairly similar to docbook, but
> this person has explicitly defined two elements -- "file-name" and
> "directory-name" -- to be used for that respective markup.
> 
>    i'm aware that docbook has the standard "filename" element and, as
> a longtime unix/linux user, i'm well aware that directories are simply
> special cases of files and i have always marked up directory names
> with just <filename>.

From a technical perspective a directory name and a file name might be the same, but the average computer
user would likely scratch his/her head at that notion. So I could imagine a situation in which an author
might want to treat the two items differently in order to communicate better with the average user.

I personally don't see the need for such a distinction in the types of documentation that I write, but I don't
think it's that strange. So as usual, "it depends".  :-)

*************************
Rob Cavicchio
Principal Technical Writer & Information Architect
EMC Captiva
Information Intelligence Group
EMC Corporation
3721 Valley Centre Drive, Ste 200
San Diego, CA 92130

P: (858) 320-1208
F: (858) 320-1010
(Continue reading)

Permalink | Reply | 0 comments |
headers
Robert P. J. Day | 7 Jul 2011 14:42
Picon
Gravatar

the proper markup for displaying a file snippet?

   (apologies for such trivial questions -- i'm only just getting back  
to docbook after quite some time away.)

   if i wanted to display the contents (or an excerpt thereof) of a  
simple text file such as, say, a config file, what is the semantically  
proper element?  i don't want to use <programlisting> because it's not  
technically a program.  and <literallayout> and <screenshot> seem  
similarly inappropriate.  what i want is something equivalent to  
<filelisting>.  what do people here use for that?  thanks.

rday
Permalink | Reply | 5 comments |
headers
davep | 7 Jul 2011 16:05
Picon

Re: the proper markup for displaying a file snippet?

On 07/07/2011 01:42 PM, Robert P. J. Day wrote:
>   (apologies for such trivial questions -- i'm only just getting back 
> to docbook after quite some time away.)
>
>   if i wanted to display the contents (or an excerpt thereof) of a 
> simple text file such as, say, a config file, what is the semantically 
> proper element?  i don't want to use <programlisting> because it's not 
> technically a program.  and <literallayout> and <screenshot> seem 
> similarly inappropriate.  what i want is something equivalent to 
> <filelisting>.  what do people here use for that?  thanks.
>
> rday

File listings are shown as .... screenshots? Or they are 'program listings'
I think  screenshot for a config file since it isn't a program?

HTH

regards

--

-- 
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk
Permalink | Reply | 0 comments |
headers
Bob Stayton | 7 Jul 2011 18:10

Re: the proper markup for displaying a file snippet?

I think literallayout is the appropriate element.  As the Definitive Guide says, " it 
does not have strong semantic overtones". You can add a class="monospaced" attribute 
if you want that font in the output.

Bob Stayton
Sagehill Enterprises
bobs <at> sagehill.net

----- Original Message ----- 
From: "Robert P. J. Day" <rpjday <at> crashcourse.ca>
To: <docbook <at> lists.oasis-open.org>
Sent: Thursday, July 07, 2011 5:42 AM
Subject: [docbook] the proper markup for displaying a file snippet?

>   (apologies for such trivial questions -- i'm only just getting back  to docbook 
> after quite some time away.)
>
>   if i wanted to display the contents (or an excerpt thereof) of a  simple text file 
> such as, say, a config file, what is the semantically  proper element?  i don't want 
> to use <programlisting> because it's not  technically a program.  and 
> <literallayout> and <screenshot> seem  similarly inappropriate.  what i want is 
> something equivalent to  <filelisting>.  what do people here use for that?  thanks.
>
> rday
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe <at> lists.oasis-open.org
> For additional commands, e-mail: docbook-help <at> lists.oasis-open.org
>
(Continue reading)

Permalink | Reply | 0 comments |
headers
Jirka Kosek | 8 Jul 2011 12:16
Picon
Favicon
Gravatar

Re: the proper markup for displaying a file snippet?

On 7.7.2011 14:42, Robert P. J. Day wrote:

>   if i wanted to display the contents (or an excerpt thereof) of a
> simple text file such as, say, a config file, what is the semantically
> proper element?  i don't want to use <programlisting> because it's not
> technically a program. 

I think that using programlisting for configuration files is approriate.
It's very hard to draw clear line between configuration files and
programw written in some highly declarative or DSL languages.

		Jirka

--

-- 
------------------------------------------------------------------
  Jirka Kosek      e-mail: jirka <at> kosek.cz      http://xmlguru.cz
------------------------------------------------------------------
       Professional XML consulting and training services
  DocBook customization, custom XSLT/XSL-FO document processing
------------------------------------------------------------------
 OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
------------------------------------------------------------------
Permalink | Reply | 2 comments |
headers
Norman Walsh | 14 Jul 2011 21:44
Favicon
Gravatar

Re: the proper markup for displaying a file snippet?

Jirka Kosek <jirka <at> kosek.cz> writes:
> I think that using programlisting for configuration files is approriate.
> It's very hard to draw clear line between configuration files and
> programw written in some highly declarative or DSL languages.

Indeed. I sometimes (ab)use "screen" for things that aren't properly
program listings within the context of what I'm writing. I have, for
example, sometimes configured line numbers for programlistings but not
for screens.

The semantics of literallayout are certainly loose enough to fit the
case, though I still tend to think of that for poetry or other
prose-ish sorts of things that happen to need specific line breaks.

                                        Be seeing you,
                                          norm

--

-- 
Norman Walsh <ndw <at> nwalsh.com>      | Science is organized knowledge.
http://www.oasis-open.org/docbook/ | Wisdom is organized
Chair, DocBook Technical Committee | life.--Immanuel Kant
Permalink | Reply | 1 comment |
headers
Peter Flynn | 16 Jul 2011 00:13
Picon

Re: Re: the proper markup for displaying a file snippet?

On 14/07/11 20:44, Norman Walsh wrote:
> Jirka Kosek<jirka <at> kosek.cz>  writes:
>> I think that using programlisting for configuration files is approriate.
>> It's very hard to draw clear line between configuration files and
>> programw written in some highly declarative or DSL languages.
>
> Indeed. I sometimes (ab)use "screen" for things that aren't properly
> program listings within the context of what I'm writing. I have, for
> example, sometimes configured line numbers for programlistings but not
> for screens.

I would use programlisting for config files as well as program code, 
because they are semantically close enough to warrant it IMHO.

I've never used screen, and I've only used screenshot for console i/o 
when documenting the use of a CLI because "screenshot" to me implies a 
graphic of a window or screen to me, rather than text.

> The semantics of literallayout are certainly loose enough to fit the
> case, though I still tend to think of that for poetry or other
> prose-ish sorts of things that happen to need specific line breaks.

That was my understanding, although I would tend to use TEI for literary 
documents rather than DocBook.

I don't think it matters a whole lot so long as you're consistent, and 
you document it if you feel it's open to misinterpretation.

///Peter
(Continue reading)

Permalink | Reply | 0 comments |

Gmane