From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from omta001.cacentral1.a.cloudfilter.net (omta001.cacentral1.a.cloudfilter.net [3.97.99.32]) by sourceware.org (Postfix) with ESMTPS id 369F8385AC35 for ; Sat, 19 Feb 2022 05:31:18 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 369F8385AC35 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=SystematicSw.ab.ca Authentication-Results: sourceware.org; spf=none smtp.mailfrom=systematicsw.ab.ca Received: from shw-obgw-4002a.ext.cloudfilter.net ([10.228.9.250]) by cmsmtp with ESMTP id L7nZntkil43SgLIKznvjux; Sat, 19 Feb 2022 05:31:17 +0000 Received: from [10.0.0.5] ([184.64.124.72]) by cmsmtp with ESMTP id LIKznmvfDqyysLIKznzo0n; Sat, 19 Feb 2022 05:31:17 +0000 X-Authority-Analysis: v=2.4 cv=Y6brDzSN c=1 sm=1 tr=0 ts=621080a5 a=oHm12aVswOWz6TMtn9zYKg==:117 a=oHm12aVswOWz6TMtn9zYKg==:17 a=IkcTkHD0fZMA:10 a=TImcKGuyeGIbufSLrCcA:9 a=QEXdDO2ut3YA:10 Message-ID: Date: Fri, 18 Feb 2022 22:31:16 -0700 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:91.0) Gecko/20100101 Thunderbird/91.6.0 Reply-To: newlib@sourceware.org Subject: Re: [PATCH 0/1] newlib/libc/time/tzset_r.c(_tzset_unlocked_r): add POSIX <> quoted abbrs Content-Language: en-CA To: newlib@sourceware.org References: <20220215215701.40283-1-Brian.Inglis@SystematicSW.ab.ca> <1451bc59-821e-aa0f-100a-8abceca94662@SystematicSw.ab.ca> <66b3d84e-4faf-711b-ab2b-855554c3fafa@SystematicSw.ab.ca> From: Brian Inglis Organization: Systematic Software In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit X-CMAE-Envelope: MS4xfIuvNEeWdUi6AI7Zdyb4YD6h5Bl8KwJIlV9pk704zq/naVKQSGTidOBvA/+dpT/TCdln4ZCPCwbrge28Fs+XshboaVJAv0dmXGVU4nwGAUJrngHYIrD9 D5IvfRjlj2I6rHHhkkHGtZTnTZKo4vgUAlk2V5+QXVK2mgM6Xe4uuHqBw1V4vSEbTh6CeplLRrqpEXS6spswASKtgVwObSd0RTI= X-Spam-Status: No, score=-1163.6 required=5.0 tests=BAYES_00, KAM_DMARC_STATUS, KAM_LAZY_DOMAIN_SECURITY, NICE_REPLY_A, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=no autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: newlib@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Newlib mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 19 Feb 2022 05:31:20 -0000 On 2022-02-18 07:16, Jon Turney wrote: > On 18/02/2022 03:43, Brian Inglis wrote: >> On 2022-02-17 05:11, Corinna Vinschen wrote: >>> On Feb 16 12:18, Brian Inglis wrote: >>>> On 2022-02-16 01:55, Corinna Vinschen wrote: >>>>> On Feb 15 22:38, Brian Inglis wrote: >>>>>> I am inclined to use if defined in order: >>>>>> *    limits.h TZNAME_MAX >>>>>> *    unistd.h sysconf(_SC_TZNAME_MAX) if available >>>>>> *    limits.h _POSIX_TZNAME_MAX >>>>>> *    6! >>>>> >>>>> I'd replace 6 with #error >>>> >>>> That's probably for the best - I'll look at adding that to a v2 >>>> patch set >>>> including doc update. >>>> >>>> What is required to remake newlib libc info and man pages? >>> >>> make info / make man? >> >> Thanks for the kick! >> I finally found those targets under build64/newlib/Makefile and got >> errors: it looks like python {lxml,ply} need to be manually upgraded >> to python39-{lxml,ply} for these to work! >> >> Both the updated tzset info and man pages now look awful with a >> screenful of run on text! > > That's odd since I would think the viewer should wrap appropriately. There are now nested lists of fields and definitions which were indeed wrapped: into a single run on paragraph with no indentation or breaks, so it looks like the makedocbook docs mostly don't apply here! >> As far as I can see, I can only use blank lines and angle brackets for >> formatting, so I will add a whole bunch more of those, retry if they >> will now build as part of Cygwin, and see if I can get them to look >> much better. >> >> If anyone has any pointers to the embedded lib doc header semantic >> formatting conventions I would be grateful for those. > > Yeah, this should be described in the documentation section of the > 'HOWTO' file, but isn't. > > Briefly: > > '<<' and '>>' mark up function names and code > '<[' and ']>' mark up formal parameter and variable names > > There are formatting instructions for bullet points, preformatted > monospaced text and tables, which are probably best understood by > looking at an existing example. I did get bullet lists working with "*- " prefix which marked with "- " but not "*", "* ", "**", "** "! I used <[...]> and blank lines extensively to provide emphasis which mostly works in man pages, but as info pages convert those to uppercase, could not distinguish from uppercase literals, so I had to add the convention that those are indicated by apostrophe single quotes 'X' in both formats, although unnecessary in man pages, while in man format two adjacent variable names are concatenated, which I could not separate without inserting a visible character, which would be more confusing! ;^< > In theory, you can also use any texinfo markup, but if you use anything > outside the very limited subset currently used and understood by > makedocbook. > > Unfortunately, makedocbook relies on the prototypes being marked-up in > quite an exact way in order to be able to massage them into the very > detailed content model of a docbook funcsynopsis. I'll browse the other functions to see if I can find more example markup, but those constructs look more like what I would expect in guile or m4 scripts than makedocbook, which seems natively to be closer to restructured text or markdown: I prefer the latter over the former! -- Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada This email may be disturbing to some readers as it contains too much technical detail. Reader discretion is advised. [Data in binary units and prefixes, physical quantities in SI.]