Horton

Re: documentation structure

jian he <jian.universality@gmail.com>

View thread
From: jian he <jian.universality@gmail.com>
To: "David G. Johnston" <david.g.johnston@gmail.com>
Cc: Tatsuo Ishii <ishii@postgresql.org>, andrew@dunslane.net, corey.huinker@gmail.com, robertmhaas@gmail.com, pgsql-hackers@postgresql.org
Date: 2024-07-19T06:55:00Z
Lists: pgsql-hackers

Commits

Same data as JSON: GET /api/v1/messages/:b64id/commits the thread's linked commits as JSON, with link sources. API reference →

  1. docs: Consistently use <optional> to indicate optional parameters

  2. docs: Consolidate into new "WAL for Extensions" chapter.

  3. freespace: Don't return blocks past the end of the main fork.

  4. docs: Merge separate chapters on built-in index AMs into one.

  5. docs: Demote "Monitoring Disk Usage" from chapter to section.

  6. doc: move system views section to its own chapter

Attachments

On Fri, Jul 19, 2024 at 12:07 PM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
> On Thu, Jul 18, 2024 at 8:06 PM Tatsuo Ishii <ishii@postgresql.org> wrote:
>>
>> > I'm opposed to having a separate file for every function. I think
>> > breaking up func.sgml into one piece per sect1 is about right. If that
>> > proves cumbersome still we can look at breaking it up further, but
>> > let's start with that.
>>
>> That will create at least 30 func-xx.sgml files.
>>
>> t-ishii$ grep '<sect1' func.sgml|wc -l
>> 30
>>
>> I am afraid that's too many?
>>
>
> The premise and the resultant number of files both seem reasonable to me.  I could get that number down to maybe 20 if pressed but I don't see any benefit to doing so. I look at a page on the website that needs updating then go open its source file.  Nice and tidy.
>

hi. my python test.py script in [1] cut func.sgml from 31k lines to
13k lines by putting some contents to these 7 new files.
        new file:   func-admin.sgml
        new file:   func-aggregate.sgml
        new file:   func-datetime.sgml
        new file:   func-info.sgml
        new file:   func-json.sgml
        new file:   func-matching.sgml
        new file:   func-string.sgml

doc/src/sgml/filelist.sgml changes are addressed in the attached patch.
cutting func.sgml into half is ok for me.


in test.py , at line 35, i use
"os.chdir("/home/jian/Desktop/pg_src/src7/postgres/doc/src/sgml")"
you need to change to your corresponding "doc/src/sgml" directory.
overall, you need apply the attached patch, change test.py line 35.



main gotcha is based on pattern mentioned in [2] and
index layout from https://www.postgresql.org/docs/devel/functions.html

[1] https://postgr.es/m/CACJufxH%2BYi521QrncwnW4sFGOhPmJQpsmoJ%2BYnj%2BVpHu5wAahQ%40mail.gmail.com\
[2] http://postgr.es/m/CACJufxEcMjjn-m6fpC2wXHsQbE5nyd%3Dxt6k-jDizBVUKK6O4KQ%40mail.gmail.com