Can we add the corresponding link to the keyword representing the data source like m o p, for example: p<https://www.postgresql.org/docs/16/functions-formatting.html#FUNCTIONS-FORMATTING-DATETIME -TABLE> But selecting the data source version also seems to be a problem
Thanks as always, Cancai Cai On 2024/01/24 22:07:23 Julian Hyde wrote: > The current review process is that I hand-edit most of the submissions. (Or > make detailed suggestions: ‘Convert this verb from declarative to imperative. > Remove the space before the open parenthesis.') I we increase the scope of > the documentation, that puts more burden on me. > > We should not increase the scope of the documentation unless we introduce > generation. Generation will at least allow us to automate some checks. Such > as that the examples actually parse, and return the results the doc says they > do. > > Julian > > > > On Jan 24, 2024, at 1:55 PM, Mihai Budiu <[email protected]> wrote: > > > > I am not proposing a new process, the existing review process would > > continue to apply. The page would still be part of the repository. Just a > > separate web page on the calcite site, unbundled from the SQL language page. > > > > Mihai > > > > ________________________________ > > From: Julian Hyde <[email protected]> > > Sent: Wednesday, January 24, 2024 1:27 PM > > To: [email protected] <[email protected]> > > Subject: Re: Refactor reference.md > > > > "The documentation would be incrementally improved, like the code base." Or > > it might incrementally decline into a shambles. Sure, this is open source, > > and open source can sometimes create miracles, but we need to be realistic. > > We need an owner, and systems in place, to overcome the effects of entropy. > > > > Other products have a separate page for each function, and an index > > containing all functions. For example, see PostGIS: > > https://postgis.net/docs/manual-1.5/ST_MakeLine.html. But take a look at > > the meta tags at the top of the page - it’s generated from DocBook. That is > > a tell that it is maintained by a professional writer. > > > > Julian > > > > > > > >> On Jan 24, 2024, at 1:12 PM, Mihai Budiu <[email protected]> wrote: > >> > >> The documentation would be incrementally improved, like the codebase. > >> We could start by just moving it to a different file. The narrow table > >> also makes it difficult to read, so perhaps we can reformat that. A third > >> column would be nice for examples, but it would mostly be empty initially. > >> Some functions require additional clarifications as long text, maybe these > >> can be footnotes? > >> > >> Another solution is to make a separate table for each class of functions: > >> string, numeric, array, etc. That would make it easier to intersperse with > >> additional notes. > >> > >> The terse format makes it very difficult to explain things that are > >> subtle. For example, see my PR https://github.com/apache/calcite/pull/3571 > >> which only attempts to clarify something, but has not been approved since > >> early December. > >> > >> Mihai > >> ________________________________ > >> From: Julian Hyde <[email protected]> > >> Sent: Wednesday, January 24, 2024 12:54 PM > >> To: [email protected] <[email protected]> > >> Subject: Re: Refactor reference.md > >> > >> Extra documentation would be nice. But who is going to write (and > >> maintain) this extra documentation? > >> > >> Even the current documentation takes a lot of work. When reviewing a PR to > >> add a function, I have to tell people to remove a ‘.’ at the end of the > >> line to be consistent with the existing doc. Without those efforts, the > >> documentation would be a shambles, and no one would trust it. We have over > >> 500 functions. > >> > >> Julian > >> > >> > >>> On Jan 24, 2024, at 9:46 AM, Mihai Budiu <[email protected]> wrote: > >>> > >>> I think we should make a separate document for the functions, and in > >>> general give more details about the functions' behavior. The current > >>> model is to give a very brief description of the function, but that's > >>> often not enough, users have to resort to either experiments or to > >>> reading documentation from other databases. The behavior should be > >>> described for corner cases, and ideally there should be examples as well. > >>> > >>> Mihai > >>> ________________________________ > >>> From: Cancai Cai <[email protected]> > >>> Sent: Wednesday, January 24, 2024 7:14 AM > >>> To: [email protected] <[email protected]> > >>> Subject: Refactor reference.md > >>> > >>> Hey Calcite Devs, > >>> > >>> I am currently working on CALCITE-6215 > >>> <https://issues.apache.org/jira/browse/CALCITE-6215>. During my work, I > >>> have noticed that certain functions have multiple variations with > >>> different > >>> parameter types in their respective databases. For example, in PostgreSQL, > >>> the to_char function supports multiple forms such as to_char(timestamp, > >>> text), to_char(interval, text), and to_char(numeric_type, text). > >>> > >>> However, the description in Calcite is not clear enough. For instance, the > >>> reference.md document describes the to_char function as follows: > >>> > >>> | m o p | TO_CHAR(timestamp, format) | Converts *timestamp* to a string > >>> using the format *format*. > >>> > >>> This description may not provide enough clarity for users to understand > >>> the > >>> usage of each function across different databases. > >>> > >>> I suggest considering adding specific links to the corresponding database > >>> functions in the reference.md document to enhance its completeness. This > >>> would allow users to easily access the documentation for the respective > >>> database functions. > >>> > >>> Thanks as always, > >>> > >>> Cancai Cai > >>> > >>> https://www.postgresql.org/docs/16/functions-formatting.html#FUNCTIONS-FORMATTING-DATETIME-TABLE > >> > > > >
