From nobody Tue Jan 31 09:02:55 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 4P5fGM3Vpnz3btKs for ; Tue, 31 Jan 2023 09:03:07 +0000 (UTC) (envelope-from carlavilla@freebsd.org) Received: from smtp.freebsd.org (smtp.freebsd.org [IPv6:2610:1c1:1:606c::24b:4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "smtp.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4P5fGM33sSz46vK; Tue, 31 Jan 2023 09:03:07 +0000 (UTC) (envelope-from carlavilla@freebsd.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1675155787; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=LhU+oNbPNHqb9qzmypwl2upBmAgOkt8r7uEjef2Brqw=; b=CH7mA1e6PGfEfRk2g72k9da7UmbLuG89zKibvdAXk0JT77TO0RSrxEdkrnVhnPXP5Tl32x H9kH/q8Gg9Ezwvc7wzudbr8zcnuzzma1TtplxLzlj877yHych4mRY0cZyywe0Fi3qR/pUh EYAGXiRdgbd+Xb+Y2B1rrvtihOGc1mvU7FS9VRs3CVgtP82EFRLR0ILzvqDbNJylTfNSXu sHo8FB46WdqDjAsFj9dmDhUyDTR5YYiAVMy+dkhTdNjDIfZfKW6KUWPK2dRH0wIDGL1clV BVke1kZkIG44clptWoL4YrRo3rg5rq2i0cQKJ7lj0rGkKTGVLzxj8iXcVO14+A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1675155787; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=LhU+oNbPNHqb9qzmypwl2upBmAgOkt8r7uEjef2Brqw=; b=c3eOD8POLQoz+mMu6S+sqf/+URcmEdmvn53DrSpb4HvMVugep46F6HU9ca2sQ3fabc1zvQ 5r7PrGVqV3/l4vCw9QVTfYktVFjx2sNvEmiNGN0UDtf8NQgR3kYFG9U3pcT3ptjhjkAlkt 0yHnn8tPzYgg/PIuoWZRpLb/qxqXy5ylGxbEymyUoG/1ifK5342eirl27YijdbndfWirqh ONa2AFxyIgGXJEU0lZFjmemsfF/b8Uj19tkPGUiZ3pPPPm8SyWb3SWZ0pYeorSar2qFihT j7V7dKry2yMrU1+wXxjzSars5MVUl64XkXxr7IBdpIXoHOAuAHNk0K1FfDs0rA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1675155787; a=rsa-sha256; cv=none; b=tGdRH5Ovk5rlF6GWdfYIvySMuUbd6SRIVnR26zIj15OlHUO+GWel6RntrPxG+jZmLXeSuX gRqZq7xd4HgUZuh87OVwd/Z21CQzGttQsT6OVYOyvlsY44gnFb2QqNhA0IgXb06NYRPYf3 HYY1uNQoerIpLtzM9TxlpdGHRYwhAYixCRTK2HzIVzUyB7R+KrxJAvC0ydDs/YfIkOGAIj 5ZZN5lWIdYmhEdeJScXmpKTiaehlWZE/G5WPCZw9BHyIRNA4utlBnHaHLxVbKy4WsA9T+7 VWkFXHMQGwbUJ7b9QSBb1NWr3BDxR23w5WTq+C4CtQYq595OgnInvdJA4mi+/A== Received: from mail-oa1-f49.google.com (mail-oa1-f49.google.com [209.85.160.49]) (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)) (Authenticated sender: carlavilla) by smtp.freebsd.org (Postfix) with ESMTPSA id 4P5fGM1zvbzWGy; Tue, 31 Jan 2023 09:03:07 +0000 (UTC) (envelope-from carlavilla@freebsd.org) Received: by mail-oa1-f49.google.com with SMTP id 586e51a60fabf-163bd802238so6352170fac.1; Tue, 31 Jan 2023 01:03:07 -0800 (PST) X-Gm-Message-State: AO0yUKVo2cKUzdmdgz5Q+YCf6H+yjKxsFRgiQNC0sliCzkToStTBUHIB qa9QvcjVPP+A66LycYZR7dKGLMebsKlDV5+S1d4= X-Google-Smtp-Source: AK7set+MUc5iFbC4/fWfbrcoYwJXsXYy8+5bwcslIdiS3Ym9IA2G+BBUA8aRIS0R9QDSkQkBgKrSzItA9Yk0h2gMydc= X-Received: by 2002:a05:6870:b156:b0:163:4864:9bf0 with SMTP id a22-20020a056870b15600b0016348649bf0mr1967339oal.125.1675155786544; Tue, 31 Jan 2023 01:03:06 -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: From: Sergio Carlavilla Date: Tue, 31 Jan 2023 10:02:55 +0100 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: To be deprecated [.filename]## tag in the document? To: ykla Cc: Mathieu Arnold , doceng@freebsd.org, "freebsd-doc@FreeBSD.org" Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-ThisMailContainsUnwantedMimeParts: N On Tue, 31 Jan 2023 at 09:47, ykla 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 =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 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!