Many posts contain files' names and also the code contained in them. Usually I have found the file names formatted as code (my_file.py
), in bold (my_file.py) or without format at all.
What's the formal way to format the file names?
There is no formal answer in the formatting section of help for this. Thus at least I feel that the correct way to do it isn't about the format used but rather about consistence within the post. Also another point to be taken into consideration is the readability that can be improved greatly by differing between code blocks
and file names if both are regularly used in the code.
At first sight, using code
format is appealing. A file name may be thought of as being somewhat similar to code. As @LightnessRacesinOrbit so appropriately puts it in a comment, a file is a "thing that is quoted verbatim from a computer terminal", and thus it (more or less) qualifies as code. Still, in certain cases it may be desirable to have a format to distinguish file names from (the rest of the) code.
Another possibility is to use italic or bold. That way the file name is distinguished from actual code. But italic or bold are often used for emphasis. It would be best not to confuse a file name with an emphasized word or phrase.
Taking this into account, a good solution may be to use italic code
or bold code
format for file names. That way the filename looks similar to code, but there's a distinction. (And of course it should be used consistently thoughout the post, as mentioned by sanfor.)
-v
, etc.
Commented
Aug 24, 2015 at 16:27
Sometimes file names are specific commands to be run, and in that instance I think code formatting is most appropriate: netsh.exe show mode
.
There are different options:
plugin.yml
plugin.yml
plugin.yml
plugin.yml
Personally, I use italic formatting.
<kbd>
tag in markup is not appropriate for a filename, in general. "The <kbd> HTML element represents a span of inline text denoting textual user input from a keyboard, voice input, or any other text entry device." per developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd
<kbd>
tag: when the document is directing a user to type a filename. Generally speaking, this is not how filenames are used in documentation.
At least with code, we use file names—verbally and in writing—almost like the title of the contents within the files.
For a creative work, such as a novel or a film, we italicize the title of the work. Although I'll never write a piece of code as magnificent as The Lord of the Rings, I don't think it's too much of a stretch to consider code as a type of composition and to suggest that we use italics when citing the "titles":
As illustrated above, italics provide a reasonable distinction for file names, at least visually. For those of us resolutely concerned about the semantics of markup generated, we can use <i>…</i>
tags in place of markdown to avoid designating titles as emphasis.
Speaking of semantics, inline code formatting
seems like fair option, but I think we can distinguish between referring to a file ("here's my .htaccess") and describing a file name used in code or a command ("check that somefile.csv
exists in that function") by marking the former with italics and the latter as code.
In my opinion, all code related things should be used in code blocks
, thus being more pleasant for the viewer. But it doesn't have a formal way to do that.
oh this name has spaces.and.dots
which may be hard to read without the file in inline code style. Italics or bold don't solve the problem well since they don't "bind" the parts of the file name as closely as the code style box.