Re: Line breaks in @file{} entries?

[Trevor Daniels]

Valentin Villenave wrote Friday, November 26, 2010 3:00 PM
> Here's what I'm thinking (I'll update the doc guidelines if you 
> guys agree):
>
> @file{} entries should not contain a @/ escape sequence, unless 
> these
> are long enough to justify a possible line break.

Tick, as a policy statement.

> Long entries are those who contain either more than one dash or 
> more
                                          that  :)
> than one slash (not counting "../").
>
> Examples:
> Write
>  @file{scm/lily.scm}
> or
>  @file{scm/backend-library.scm}
>
> but
>  @file{scm/define@/-markup@/-commands.scm}
> or
>  @file{input/@/regression/@/note-names.ly}

Hhm.  Not sure.  I think I'd prefer "more than three dashes or 
slashes",
if we are to do it that way, but really it depends more on the total 
length
of the name rather than the number of dashes and slashes.  I'd 
prefer
"if the name is longer than 50 characters (say)".

And if the name is too long then I'd prefer to place a single 
optional break
near to the middle, so we don't get tiny fragments at the end or 
start of
lines.

Or as Graham suggests, use @example.

> [Optionally:
> @file{} entries in @seealso sections should not contain @/ 
> escaping,
> no matter how long they are.]

Tick

Trevor