Date: Tue, 31 Jan 2023 16:47:02 +0800 From: ykla <yklaxds@gmail.com> To: Mathieu Arnold <mat@freebsd.org> Cc: Sergio Carlavilla <carlavilla@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: <CA%2BPGaYC-_zudANd5ZUH=_rJj69w5JYRkSVs_t9ziDXQuUqc=4g@mail.gmail.com> In-Reply-To: <20230131080243.zsxwgvx6qxfjjdc3@aching.in.mat.cc> 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>
next in thread | previous in thread | raw e-mail | index | archive | help
--000000000000e6013c05f38b6087 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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 > 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 t= he > > > > > 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 le= t > > > 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 fixe= d > > > 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 > --000000000000e6013c05f38b6087 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable <div dir=3D"ltr">So why not just use markdown, which is simpler and easier = for more people to learn? Just like vuepress=C2=A0<a href=3D"https://handbo= ok.bsdcn.org/">https://handbook.bsdcn.org/</a>; .<br></div><br><div class=3D= "gmail_quote"><div dir=3D"ltr" class=3D"gmail_attr">Mathieu Arnold <<a h= ref=3D"mailto:mat@freebsd.org">mat@freebsd.org</a>> =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= <br></div><blockquote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8= ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On Mon, Jan 30,= 2023 at 12:43:27PM +0100, Sergio Carlavilla wrote:<br> > On Mon, 30 Jan 2023 at 12:31, Mathieu Arnold <<a href=3D"mailto:mat= @freebsd.org" target=3D"_blank">mat@freebsd.org</a>> wrote:<br> > ><br> > > On Mon, Jan 30, 2023 at 11:36:05AM +0100, Sergio Carlavilla wrote= :<br> > > > El jue., 26 ene. 2023 8:21, ykla <<a href=3D"mailto:yklax= ds@gmail.com" target=3D"_blank">yklaxds@gmail.com</a>> escribi=C3=B3:<br= > > > ><br> > > > > Hi,<br> > > > ><br> > > > > I see that in some sections the [.filename]# # tags hav= e been replaced<br> > > > > with ` `, which does not effectively distinguish betwee= n folders, device<br> > > > > symbols and specific commands, etc.<br> > > > ><br> > > > >=C2=A0 Are there any plans for FreeBSD to do this across= the board in the<br> > > > > future? I.e., do we need to do away with the [.filename= ]# # tag?<br> > > > ><br> > > > > ykla<br> > > > > .<br> > > > ><br> > > ><br> > > > Hi,<br> > > ><br> > > > Yes, the idea is to remove the [.filename]## tag and use ``<= br> > > ><br> > > > This is from the migration of Docbook to AsciiDoc.<br> > ><br> > > But, why?<br> > ><br> > > This feels like a regression, docbook allowed us to mark things u= p<br> > > semantically, like, we would know what was a variable, a filename= , a<br> > > code block... The idea was to be able to differentiate things, an= d let<br> > > the rendering do the right thing.<br> > > If I see [.filename]#PKG# I clearly see it refers to a filename, = they<br> > > used to be rendered as fixed with, in some color, so that they co= uld be<br> > > differentiated from other fixed width stuff.<br> > > If I see `PKG` I just see something that will be rendered with a = fixed<br> > > with font, but I have no idea what it refers to.<br> > ><br> > > --<br> > > Mathieu Arnold<br> > <br> > Hi,<br> > <br> > > This feels like a regression, docbook allowed us to mark things u= p<br> > > semantically,<br> > <br> > Yes, but this is in Docbook, not in AsciiDoc.<br> > <br> > For AsciiDoc the syntax [.whatever]## is to declare a class for the CS= S parser.<br> > The result in the HTML, PDF and EPUB will be the same.<br> > Using [.whatever]## or ``.<br> > <br> > Personally, for me it is easier to read/write `` instead of the other = option.<br> > But not only in AsciiDoc, algo in Github MD, Gitlab MD, etc.<br> > <br> > But of course, this is my personal opinion, if you think is better to<= br> > use the old syntax, please send an email to doceng@<br> > Of course, this kind of changes must be decided by the entire Doceng@<= br> > not only a member of them.<br> <br> This is exactly my point, if you write `foo`, you cannot affect the<br> rendering so that variable `foo` is different than filename `foo` or<br> code block `foo`, which is why we should keep [.filename]#foo#, and if<br> it was ever a thing, [.variable]#foo#, so that rendering can be made<br> different, and people reading the documentation have a better<br> experience, like, if something is in fixed width font, and in green,<br> (which was the color when we used docbook, I think,) then I know it's a= <br> filename, I don't have to figure it out by using context.<br> <br> -- <br> Mathieu Arnold<br> </blockquote></div> --000000000000e6013c05f38b6087--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CA%2BPGaYC-_zudANd5ZUH=_rJj69w5JYRkSVs_t9ziDXQuUqc=4g>