Thread: SGML doc file references

Hi,
I'm reading the docs (I'm trying to figure out some replication
things) and I was wondering why the file references [1] don't match
the file names.

Most of the inconsistent items are for `obsolete-*` where the filename
is actually `appendix-obsolete-*`. But, oddly, afaict, they were
introduced with these inconsistent names.

In one of those cases, the base of the file is also wrong (pgxlogdump
[2] vs. pgreceivexlog [3]). I believe this was an api change between
9.3 and 9.4. I know that there are `id=` tags designed to catch old
references, but the comments don't seem to serve that purpose, if they
are, I was wondering if an additional comment explaining their
discrepancies would be warranted.

In one case, it's just a missing `-` (`backupmanifest.sgml` vs
`backup-manifest.sgml`) which feels accidental.

(I do have more technical questions about the docs, but I think I may
try a different venue to ask them.)

Thanks,

[1] https://github.com/jsoref/postgres/commit/sgml-doc-file-refs
[2] https://www.postgresql.org/docs/9.3/pgxlogdump.html
[3] https://www.postgresql.org/docs/9.4/app-pgreceivexlog.html

On 16.06.22 19:30, Josh Soref wrote:
> I'm reading the docs (I'm trying to figure out some replication
> things) and I was wondering why the file references [1] don't match
> the file names.

I think it was never a goal to absolutely make them match all the time, 
so a lot of the differences might be accidental.  There are also some 
tooling restrictions for what characters can be in the output file names.

Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:
> I think it was never a goal to absolutely make them match all the time,
> so a lot of the differences might be accidental.

ok, are they worth fixing? It seems like it'd make sense for files to
properly reference other files so that humans don't have to go looking
for files that don't exist...

> There are also some tooling restrictions for what characters can be in the output file names.

I don't think that this applies to the changes I suggested in the
patch I attached in my initial email.

On 17.06.22 19:52, Josh Soref wrote:
> Peter Eisentraut <peter.eisentraut@enterprisedb.com> wrote:
>> I think it was never a goal to absolutely make them match all the time,
>> so a lot of the differences might be accidental.
> 
> ok, are they worth fixing?

That would require renaming either the output files or the input files, 
and people would really not like either one.

Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
> On 17.06.22 19:52, Josh Soref wrote:
>> ok, are they worth fixing?

> That would require renaming either the output files or the input files, 
> and people would really not like either one.

Agreed that renaming those files is not desirable, but the presented
patch was only fixing erroneous/obsolete comments.

            regards, tom lane

On 17.06.22 21:33, Tom Lane wrote:
> Peter Eisentraut <peter.eisentraut@enterprisedb.com> writes:
>> On 17.06.22 19:52, Josh Soref wrote:
>>> ok, are they worth fixing?
> 
>> That would require renaming either the output files or the input files,
>> and people would really not like either one.
> 
> Agreed that renaming those files is not desirable, but the presented
> patch was only fixing erroneous/obsolete comments.

Yeah, I had totally misinterpreted what was being proposed.  Of course, 
the patch is most sensible.  Committed.