Re: To be deprecated [.filename]## tag in the document?

On Mon, Jan 30, 2023 at 12:43:27PM +0100, Sergio Carlavilla wrote:
> On Mon, 30 Jan 2023 at 12:31, Mathieu Arnold <mat@freebsd.org> wrote:
> >
> > On Mon, Jan 30, 2023 at 11:36:05AM +0100, Sergio Carlavilla wrote:
> > > El jue., 26 ene. 2023 8:21, ykla <yklaxds@gmail.com> escribió:
> > >
> > > > Hi,
> > > >
> > > > I see that in some sections the [.filename]# # tags have been replaced
> > > > with ` `, which does not effectively distinguish between folders, device
> > > > symbols and specific commands, etc.
> > > >
> > > >  Are there any plans for FreeBSD to do this across the board in the
> > > > future? I.e., do we need to do away with the [.filename]# # tag?
> > > >
> > > > ykla
> > > > .
> > > >
> > >
> > > Hi,
> > >
> > > Yes, the idea is to remove the [.filename]## tag and use ``
> > >
> > > This is from the migration of Docbook to AsciiDoc.
> >
> > But, why?
> >
> > This feels like a regression, docbook allowed us to mark things up
> > semantically, like, we would know what was a variable, a filename, a
> > code block... The idea was to be able to differentiate things, and let
> > the rendering do the right thing.
> > If I see [.filename]#PKG# I clearly see it refers to a filename, they
> > used to be rendered as fixed with, in some color, so that they could be
> > differentiated from other fixed width stuff.
> > If I see `PKG` I just see something that will be rendered with a fixed
> > with font, but I have no idea what it refers to.
> >
> > --
> > Mathieu Arnold
> 
> Hi,
> 
> > This feels like a regression, docbook allowed us to mark things up
> > semantically,
> 
> Yes, but this is in Docbook, not in AsciiDoc.
> 
> For AsciiDoc the syntax [.whatever]## is to declare a class for the CSS parser.
> The result in the HTML, PDF and EPUB will be the same.
> Using [.whatever]## or ``.
> 
> Personally, for me it is easier to read/write `` instead of the other option.
> But not only in AsciiDoc, algo in Github MD, Gitlab MD, etc.
> 
> But of course, this is my personal opinion, if you think is better to
> use the old syntax, please send an email to doceng@
> Of course, this kind of changes must be decided by the entire Doceng@
> not only a member of them.

This is exactly my point, if you write `foo`, you cannot affect the
rendering so that variable `foo` is different than filename `foo` or
code block `foo`, which is why we should keep [.filename]#foo#, and if
it was ever a thing, [.variable]#foo#, so that rendering can be made
different, and people reading the documentation have a better
experience, like, if something is in fixed width font, and in green,
(which was the color when we used docbook, I think,) then I know it's a
filename, I don't have to figure it out by using context.

-- 
Mathieu Arnold