From owner-freebsd-doc@freebsd.org Mon Jun 8 16:20:11 2020 Return-Path: Delivered-To: freebsd-doc@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 7E2DB334C8A for ; Mon, 8 Jun 2020 16:20:11 +0000 (UTC) (envelope-from pauamma@gundo.com) Received: from mailman.nyi.freebsd.org (unknown [127.0.1.3]) by mx1.freebsd.org (Postfix) with ESMTP id 49gdkz2DFBz3g7g for ; Mon, 8 Jun 2020 16:20:11 +0000 (UTC) (envelope-from pauamma@gundo.com) Received: by mailman.nyi.freebsd.org (Postfix) id 4C5403349CB; Mon, 8 Jun 2020 16:20:11 +0000 (UTC) Delivered-To: doc@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 4C1DC334A9C for ; Mon, 8 Jun 2020 16:20:11 +0000 (UTC) (envelope-from pauamma@gundo.com) Received: from mail.gundo.com (gibson.gundo.com [75.145.166.65]) by mx1.freebsd.org (Postfix) with ESMTP id 49gdky3x3vz3g7f for ; Mon, 8 Jun 2020 16:20:10 +0000 (UTC) (envelope-from pauamma@gundo.com) Received: from webmail.gundo.com (variax.gundo.com [75.145.166.70]) by mail.gundo.com (Postfix) with ESMTP id 8C51B4C1180 for ; Mon, 8 Jun 2020 11:20:08 -0500 (CDT) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII; format=flowed Content-Transfer-Encoding: 7bit Date: Mon, 08 Jun 2020 18:20:08 +0200 From: Pau Amma To: doc@freebsd.org Subject: Respecting DOCDIR in share/xml/urls.ent vs. documenting constraints on it in the FDP primer User-Agent: Roundcube Webmail/1.4.1 Message-ID: <7fa464fad50a848d0ead44a4172cdd9f@gundo.com> X-Sender: pauamma@gundo.com X-Rspamd-Queue-Id: 49gdky3x3vz3g7f X-Spamd-Bar: -- Authentication-Results: mx1.freebsd.org; dkim=none; dmarc=none; spf=pass (mx1.freebsd.org: domain of pauamma@gundo.com designates 75.145.166.65 as permitted sender) smtp.mailfrom=pauamma@gundo.com X-Spamd-Result: default: False [-2.25 / 15.00]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-0.99)[-0.987]; FROM_HAS_DN(0.00)[]; RWL_MAILSPIKE_GOOD(0.00)[75.145.166.65:from]; TO_MATCH_ENVRCPT_ALL(0.00)[]; R_SPF_ALLOW(-0.20)[+a]; MIME_GOOD(-0.10)[text/plain]; TO_DN_NONE(0.00)[]; PREVIOUSLY_DELIVERED(0.00)[doc@freebsd.org]; RCPT_COUNT_ONE(0.00)[1]; NEURAL_HAM_LONG(-1.02)[-1.017]; DMARC_NA(0.00)[gundo.com]; NEURAL_SPAM_SHORT(0.15)[0.150]; RCVD_IN_DNSWL_MED(-0.20)[75.145.166.65:from]; RCVD_NO_TLS_LAST(0.10)[]; FROM_EQ_ENVFROM(0.00)[]; R_DKIM_NA(0.00)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:7922, ipnet:75.144.0.0/13, country:US]; RCVD_COUNT_TWO(0.00)[2]; MID_RHS_MATCH_FROM(0.00)[] X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.33 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 08 Jun 2020 16:20:11 -0000 Executive summary: The '' line in share/xml/urls.ent doesn't respect DOCDIR, but I'm not sure whether and how to best fix it (in the toolchain or in the FDP primer), or even if it needs to be fixed at all (eg I could be missing something). Longer version, lightly paraphrased and expanded from my mumblings in EFnet #bsddocs yesterday: I noticed that when using DOCDIR *and* the source dir isn't /parent/of/DOCDIR/doc, "make all install" generates links with the wrong prefix (in my case, /home/pauamma/doc) for URLs that in the XML source include "&url.doc.handbook;", which breaks a number of between-docs links. When using DOCDIR and the source dir *is* /parent/of/DOCDIR/doc, these links are still wrong but work *by accident* because copies of the .html files happen to be under ~/doc until the next make clean. After staring at XML source for 2 hours wondering why my links no longer worked following a source dir change, I noticed the following 3 lines in share/xml/urls.ent: I think these are what causes the problem I'm seeing. Is this problem fixable in the toolchain at all? (I have no idea how, if it is. Makefiles are mostly a mystery to me.) Or should there be a warning in the FDP primer instead to always set DOCDIR to ~/doc or something? If this is a problem to be fixed in the documentation, I think there are 2 things to change: 1- the SVN checkout examples (eg, in 1.1) need to specify something different from ~/doc for the checkout directory, and 2- the DOCDIR examples need to be reworded to specify that DOCDIR *must* be (parent of checkout dir)/doc. Opinions, suggestions, and clues all welcome.