Date: Tue, 31 Jan 2023 09:20:42 +0000 From: Ceri Davies <ceri@submonkey.net> To: Mathieu Arnold <mat@freebsd.org> Cc: Sergio Carlavilla <carlavilla@freebsd.org>, doceng@freebsd.org, ykla <yklaxds@gmail.com>, freebsd-doc@freebsd.org Subject: Re: To be deprecated [.filename]## tag in the document? Message-ID: <2D12D689-A2F5-4C7E-8394-F12D7614707B@submonkey.net> In-Reply-To: <20230131080243.zsxwgvx6qxfjjdc3@aching.in.mat.cc> References: <20230131080243.zsxwgvx6qxfjjdc3@aching.in.mat.cc>
next in thread | previous in thread | raw e-mail | index | archive | help
> On 31 Jan 2023, at 08:02, Mathieu Arnold <mat@freebsd.org> wrote: >=20 > =EF=BB=BFOn 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: >>>=20 >>=20 >>> This feels like a regression, docbook allowed us to mark things up >>> semantically, >>=20 >> Yes, but this is in Docbook, not in AsciiDoc. >>=20 >> For AsciiDoc the syntax [.whatever]## is to declare a class for the CSS p= arser. >> The result in the HTML, PDF and EPUB will be the same. >> Using [.whatever]## or ``. >>=20 >> 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. >=20 > 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. I agree that the semantics are useful and, arguably, should not have been dr= opped without discussion with doceng@ (or in earlier times, doc@) in the fir= st place. I=E2=80=99d hope that discussion could cover whether it is more i= mportant that people can contribute =E2=80=9Ceasily=E2=80=9D (and how one wo= uld measure if that is working) or a richer documentation set that can easil= y provide contextual output in various formats (and which ones are actually g= etting asked for or used). However, that all leads me back to my usual moan about engineering goals and= I wasn=E2=80=99t here and I haven=E2=80=99t succeeded in getting this acros= s before, so I=E2=80=99ll leave my opinion there. Ceri
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?2D12D689-A2F5-4C7E-8394-F12D7614707B>