Date: Thu, 7 Mar 2024 05:40:52 +0000 From: Christopher Davidson <christopher.davidson@gmail.com> To: "freebsd-doc@freebsd.org" <freebsd-doc@freebsd.org> Subject: Question relationship of builting(1) and functions refrenced through .Xr Message-ID: <BN0PR20MB375038266F5C9168D2606A58A2202@BN0PR20MB3750.namprd20.prod.outlook.com>
index | next in thread | raw e-mail
[-- Attachment #1 --] Hi Documentation Team, I am investigating some updates to manual pages and came across a “self referencing” warning from the mandoc -Tlint utility, on entries associated with the builtin(1) manual page. Some examples of this self referencing are: done(1), false(1), etc.. in particular entries on lines: 308, 309, 311,312,313,314,315,316,317,319,321,322. These lines are associated with the SEE ALSO section which convention states we should use .Xr entries which causes the self-referencing warning. Question to the group is: How does the manual page relationship work between the builtin(1) manual pages and the individual .Xr links to other pages, such as done(1) false(1)? I have a little more detail on this here: https://bughuntingfreebsd.wordpress.com/2024/03/07/fixing-self-referencing/ I am currently at a lose to address this warning as using .Xr gives a warning and using the .Nm is not the best option. Thank you in advance for any guidance or suggestions you can provide. Kind Regards, Chris [-- Attachment #2 --] <html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">; <head> <meta http-equiv="Content-Type" content="text/html; charset=Windows-1252"> <meta name="Generator" content="Microsoft Word 15 (filtered medium)"> <style><!-- /* Font Definitions */ @font-face {font-family:"Cambria Math"; panose-1:2 4 5 3 5 4 6 3 2 4;} @font-face {font-family:Aptos; panose-1:2 11 0 4 2 2 2 2 2 4;} /* Style Definitions */ p.MsoNormal, li.MsoNormal, div.MsoNormal {margin:0in; font-size:11.0pt; font-family:"Aptos",sans-serif;} a:link, span.MsoHyperlink {mso-style-priority:99; color:#467886; text-decoration:underline;} span.EmailStyle17 {mso-style-type:personal-compose; font-family:"Aptos",sans-serif; color:windowtext;} span.apple-converted-space {mso-style-name:apple-converted-space;} .MsoChpDefault {mso-style-type:export-only; font-size:11.0pt; mso-ligatures:none;} @page WordSection1 {size:8.5in 11.0in; margin:1.0in 1.0in 1.0in 1.0in;} div.WordSection1 {page:WordSection1;} --></style> </head> <body lang="EN-US" link="#467886" vlink="#96607D" style="word-wrap:break-word"> <div class="WordSection1"> <p class="MsoNormal"><span style="color:#212121">Hi Documentation Team,<o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121"> <o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121">I am investigating some updates to manual pages and came across a “self referencing” warning from the mandoc -Tlint utility, on entries associated with the builtin(1) manual page.<o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121"> <o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121"> Some examples of this self referencing are: done(1), false(1), etc.. in particular entries on lines: 308, 309, 311,312,313,314,315,316,317,319,321,322.<o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121"> <o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121">These lines are associated with the SEE ALSO section which convention states we should use .Xr entries which causes the self-referencing warning.<o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121"> <o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121">Question to the group is: How does the manual page relationship work between the builtin(1) manual pages and the individual .Xr links to other pages, such as done(1) false(1)?<o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121"> <o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121">I have a little more detail on this here:<span class="apple-converted-space"> </span><a href="https://bughuntingfreebsd.wordpress.com/2024/03/07/fixing-self-referencing/" title="https://bughuntingfreebsd.wordpress.com/2024/03/07/fixing-self-referencing/"><span style="color:#0078D7">https://bughuntingfreebsd.wordpress.com/2024/03/07/fixing-self-referencing/</span></a><o:p></o:p></span></p>; <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121"> <o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121">I am currently at a lose to address this warning as using .Xr gives a warning and using the .Nm is not the best option.<o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121"> <o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121">Thank you in advance for any guidance or suggestions you can provide.<o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121"> <o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121">Kind Regards,<o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121">Chris<o:p></o:p></span></p> <p class="MsoNormal" style="caret-color: rgb(33, 33, 33);font-variant-caps: normal;orphans: auto;text-align:start;widows: auto;-webkit-text-stroke-width: 0px;word-spacing:0px"> <span style="color:#212121"> <o:p></o:p></span></p> <p class="MsoNormal"><o:p> </o:p></p> </div> </body> </html>home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?BN0PR20MB375038266F5C9168D2606A58A2202>