Date: Tue, 31 Jan 2023 10:02:55 +0100 From: Sergio Carlavilla <carlavilla@freebsd.org> To: ykla <yklaxds@gmail.com> Cc: Mathieu Arnold <mat@freebsd.org>, doceng@freebsd.org, "freebsd-doc@FreeBSD.org" <freebsd-doc@freebsd.org> Subject: Re: To be deprecated [.filename]## tag in the document? Message-ID: <CAFwocyPcprXkWUbDS0Whs0BrLHrDLpq-9a%2BN6Pzy52SoKQW8%2BA@mail.gmail.com> In-Reply-To: <CA%2BPGaYC-_zudANd5ZUH=_rJj69w5JYRkSVs_t9ziDXQuUqc=4g@mail.gmail.com> References: <CA%2BPGaYChwV0uZi4y6fdLwFwX396tbUTzgGS7hCuxwT1LhRYr0g@mail.gmail.com> <CAFwocyO_2gzyG=qN4eiOyR12MrYBhq80mbUEB7qf6X110n5VSA@mail.gmail.com> <20230130113056.rxdp4ajyh5adayl4@aching.in.mat.cc> <CAFwocyN=itM2OTjfstiLk6FMxqvktJSs7_MguaHbhSw=WGX9Jg@mail.gmail.com> <20230131080243.zsxwgvx6qxfjjdc3@aching.in.mat.cc> <CA%2BPGaYC-_zudANd5ZUH=_rJj69w5JYRkSVs_t9ziDXQuUqc=4g@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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> =E4=BA=8E2023=E5=B9=B41=E6=9C=8831=E6=97= =A5=E5=91=A8=E4=BA=8C 16:02=E5=86=99=E9=81=93=EF=BC=9A >> >> 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=C3=B3= : >> > > > >> > > > > Hi, >> > > > > >> > > > > I see that in some sections the [.filename]# # tags have been re= placed >> > > > > 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 l= et >> > > the rendering do the right thing. >> > > If I see [.filename]#PKG# I clearly see it refers to a filename, the= y >> > > 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 fix= ed >> > > 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 CS= S 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!
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAFwocyPcprXkWUbDS0Whs0BrLHrDLpq-9a%2BN6Pzy52SoKQW8%2BA>