Date: Tue, 31 Jan 2023 20:35:55 +0000 From: Pau Amma <pauamma@freebsd.org> To: Mathieu Arnold <mat@freebsd.org> Cc: doceng@freebsd.org, ykla <yklaxds@gmail.com>, "freebsd-doc@FreeBSD.org" <freebsd-doc@freebsd.org> Subject: Re: To be deprecated [.filename]## tag in the document? Message-ID: <f62ce938f020b90c7adb10cf6d2b109b@freebsd.org> 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
[trimmed ccs and quoted text] On 2023-01-31 08:02, Mathieu Arnold wrote: > 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ó: >> > > >> > > > 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? >> > > >> > > Yes, the idea is to remove the [.filename]## tag and use `` >> > > >> > > This is from the migration of Docbook to AsciiDoc. >> > >> > 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. >> >> > 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. Will it? Or does it output (for HTML) "<spam class="whatever">...</span>? >> 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. That's as it may be, but documentation is for the benefit of consumers, not producers. (IIRC, you personally agreed to that addition to the FDP primer when I proposed it to doceng@.) This may also matter to users if any using aural stylesheets since we didn't specify any, hence on accessibility. >> 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. Have to agree here. There's a strong argument for not reinventing DocBook in AsciiDoc, but I think we can avoid that, and by and large did, without sacrificing the semantic markup we kept. -- #BlackLivesMatter #TransWomenAreWomen #AccessibilityMatters #StandWithUkrainians English: he/him/his (singular they/them/their/theirs OK) French: il/le/lui (iel/iel and ielle/ielle OK) Tagalog: siya/niya/kaniya (please avoid sila/nila/kanila)
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?f62ce938f020b90c7adb10cf6d2b109b>