Docbook discussion

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

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

headers

David Cramer | 6 Jul 2011 15:02

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)

headers

davep | 6 Jul 2011 15:49

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)

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)