From nobody Tue Jan 31 08:47:02 2023 X-Original-To: freebsd-doc@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4P5dw44vgWz3brgQ for ; Tue, 31 Jan 2023 08:47:16 +0000 (UTC) (envelope-from yklaxds@gmail.com) Received: from mail-vk1-xa30.google.com (mail-vk1-xa30.google.com [IPv6:2607:f8b0:4864:20::a30]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1D4" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4P5dw42cDFz44cy; Tue, 31 Jan 2023 08:47:16 +0000 (UTC) (envelope-from yklaxds@gmail.com) Authentication-Results: mx1.freebsd.org; none Received: by mail-vk1-xa30.google.com with SMTP id l20so7011469vkm.11; Tue, 31 Jan 2023 00:47:16 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=Sl/cLMW9jPjfLo/RmHrchXnis57lB1BQ4/0ecxTpQyU=; b=cY11EjwdqqMnVsMewcz5YqspYqtDFT14NmkSRpWPXr6h9uDkBcrnGKT918ayRE7Sir 00+4KAi4cRFIGoBjAkwX/K0WpU10/MkTEI1y03kgoqEr++2qcAoEYBBs2iLPKN418JO+ 58i5zr493c7RI0B3TjE06mPFAYpCiZfRYlcFLQSSoRtzc1/qnKipNEZ4Be/a56sgSaly LrUryRgx0Ecz6IKm99P7X5nZCOYiY3bHo5+f1USKd0Y0/jdD9tkVlvEqy4yRwbruH7F6 456qeFbp5PShZ/5MEQOA/Zm5hOw/i1MFl8cGAFIpbec2KQPSiQ0CVlEhBF3yXDJ/PTho Bs2w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=Sl/cLMW9jPjfLo/RmHrchXnis57lB1BQ4/0ecxTpQyU=; b=zRC1mZn3Ui1hbUuu6WUwbueam9K7u22ddJ2o8ieICl4EfygwoIgPYgUV2xloQhKr5I hBCeSVVmixxFD9l1Oiu5ttWprJ7dxXe7WI9INmU2stYHGI6dRdydb+42+gsUGXsHvBtV RupQb28sOOnZ3TeZhNUq7Zhl5mG8ji4eR6z7zQHx0tWIxxIdP7z5OIqp7otbHM6Am15r opEcLzEhyNSfcI9XfV9T3yJmTbOLHwhssyEc6mH4ecBsMz1M4DJ7JR0egDZhY5mCndi9 M+rZvfm2Gisdcr+0WTonM6Z77hn+LWkPpMs9N7lQVnycMhFbBauUEMrJYgi4wLaAX0nC 0R0A== X-Gm-Message-State: AO0yUKWxVRK0XwGWebeAoJjrAkz4mJyo2vLx5VWqG8kPbs9FliTZiKv3 Rh0oW2/nD/pwx+Pl3xyhtEKGVSVonZwDMtSw3d0by9iE1EqS848v1pXc1g== X-Google-Smtp-Source: AK7set8v3eGMr75uBta7DeqGy0r36CqTeiEeq+9Qm6DBxF8juKb3eF4+yuQ2AYehgrA3EibnpP3QDAUSGxlXSpPV+04= X-Received: by 2002:a1f:9e11:0:b0:3ea:464a:8f61 with SMTP id h17-20020a1f9e11000000b003ea464a8f61mr950098vke.24.1675154835241; Tue, 31 Jan 2023 00:47:15 -0800 (PST) List-Id: Documentation project List-Archive: https://lists.freebsd.org/archives/freebsd-doc List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-doc@freebsd.org MIME-Version: 1.0 References: <20230130113056.rxdp4ajyh5adayl4@aching.in.mat.cc> <20230131080243.zsxwgvx6qxfjjdc3@aching.in.mat.cc> In-Reply-To: <20230131080243.zsxwgvx6qxfjjdc3@aching.in.mat.cc> From: ykla Date: Tue, 31 Jan 2023 16:47:02 +0800 Message-ID: Subject: Re: To be deprecated [.filename]## tag in the document? To: Mathieu Arnold Cc: Sergio Carlavilla , doceng@freebsd.org, "freebsd-doc@FreeBSD.org" Content-Type: multipart/alternative; boundary="000000000000e6013c05f38b6087" X-Rspamd-Queue-Id: 4P5dw42cDFz44cy X-Spamd-Bar: ---- X-Spamd-Result: default: False [-4.00 / 15.00]; REPLY(-4.00)[]; ASN(0.00)[asn:15169, ipnet:2607:f8b0::/32, country:US] X-Rspamd-Pre-Result: action=no action; module=replies; Message is reply to one we originated X-ThisMailContainsUnwantedMimeParts: N --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 =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 wrote: > > > > > > On Mon, Jan 30, 2023 at 11:36:05AM +0100, Sergio Carlavilla wrote: > > > > El jue., 26 ene. 2023 8:21, ykla 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
So why not just use markdown, which is simpler and easier = for more people to learn? Just like vuepress=C2=A0https://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 hav= e been replaced
> > > > with ` `, which does not effectively distinguish betwee= n folders, device
> > > > symbols and specific commands, etc.
> > > >
> > > >=C2=A0 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 ``<= br> > > >
> > > This is from the migration of Docbook to AsciiDoc.
> >
> > But, why?
> >
> > This feels like a regression, docbook allowed us to mark things u= p
> > semantically, like, we would know what was a variable, a filename= , a
> > code block... The idea was to be able to differentiate things, an= d 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 co= uld 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 u= p
> > 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<= br> > use the old syntax, please send an email to doceng@
> Of course, this kind of changes must be decided by the entire Doceng@<= br> > 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--