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

On Tue, 31 Jan 2023 at 10:02, Sergio Carlavilla <carlavilla@freebsd.org> wrote:
>
> On Tue, 31 Jan 2023 at 09:47, ykla <yklaxds@gmail.com> wrote:
> >
> > So why not just use markdown, which is simpler and easier for more people to learn? Just like vuepress https://handbook.bsdcn.org/ .
> >
> > Mathieu Arnold <mat@freebsd.org> 于2023年1月31日周二 16:02写道：
> >>
> >> 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
>
> Hi,
>
> There's no *one* MD, there're a lot of flavours. Not only one.So you
> cannot "learn'' one MD, you need to learn a lot of them.Also, AsciiDoc
> has some functionalities that MD doesn't have, like callouts,
> admonitions, etc.
>
> And the good point of AsciiDoc is there's only one AsciiDoc. You only
> need to learn a single one. And as I said, have some functionalities
> from the beginning without extensions, like callouts, etc. Apart from
> the possibility to build custom functions, like the package, man, git
> we're using right now.
>
> Bye!

I forgot to say two things:

In the first place, I'm gonna discuss with other Doceng members about
the [filename] thing

Secondly, I don't want to create a bikeshed about MD vs AsciiDoc.

Bye!