Re: Patch to document base64 encoding
От | Karl O. Pinc |
---|---|
Тема | Re: Patch to document base64 encoding |
Дата | |
Msg-id | 20190713170337.454193bb@slate.karlpinc.com обсуждение исходный текст |
Ответ на | Re: Patch to document base64 encoding (Fabien COELHO <coelho@cri.ensmp.fr>) |
Ответы |
Re: Patch to document base64 encoding
(Fabien COELHO <coelho@cri.ensmp.fr>)
Re: Patch to document base64 encoding (Fabien COELHO <coelho@cri.ensmp.fr>) |
Список | pgsql-hackers |
Hi Fabien, Attached is doc_base64_v10.patch On Fri, 12 Jul 2019 15:58:21 +0200 (CEST) Fabien COELHO <coelho@cri.ensmp.fr> wrote: > >> I suggested "Function <>decode</> ...", which is the kind of thing > >> we do in academic writing to improve precision, because I thought > >> it could be better:-) > > > > "Function <>decode</> ..." just does not work in English. > > It really works in research papers: "Theorem X can be proven by > applying Proposition Y. See Figure 2 for details. Algorithm Z > describes whatever, which is listed in Table W..." I've not thought about it before but I suppose the difference is between declarative and descriptive, the latter being more inviting and better allows for flow between sentences. Otherwise you're writing in bullet points. So it is a question of balance between specification and narration. In regular prose you're always going to see the "the" unless the sentence starts with the name. The trouble is that we can't start sentences with function names because of capitalization confusion. > > I hope that 3 patches will make review easier. > > Not really. I'm reviewing the 3 patches put together rather than each > one individually, which would require more work. I figured with e.g. a separate patch for moving and alphabetizing that it'd be easier to check that nothing got lost. Anyhow, Just one patch this time. > convert: I'd merge the 2 first sentences to state that if convert > from X to Y. The doc does not say explicitely what happens if a > character cannot be converted. After testing, an error is raised. The > example comment could add ", if possible". Done. Good idea. I reworked the whole paragraph to shorten and clarify since I was altering it anyway. This does introduce some inconsistency with wording that appears elsewhere but it seems worth it because the listentry box was getting overfull. > to_hex: add "." at the end of the sentence? I left as-is, without a ".". The only consistent rule about periods in the listentrys seems to be that if there's more than one sentence then there's periods -- I think. In any case a lot of them don't have periods and probably don't need periods. I don't know what to do and since the original did not have a period it seems better to leave well enough alone. > Minor comment: you usually put two spaces between a "." and the first > world of then next sentence, but not always. I now always put 2 spaces after the end of a sentence. But I've only done this where I've changed text, not when moving pre-existing text around. Again, there seems to be no consistency in the original. (I believe docbook redoes all inter-sentence spacing anyway.) Thanks for the help. I'll be sure to sign up to review a patch (or patches) when life permits. Regards, Karl <kop@karlpinc.com> Free Software: "You don't pay back, you pay forward." -- Robert A. Heinlein
Вложения
В списке pgsql-hackers по дате отправления:
Предыдущее
От: Tomas VondraДата:
Сообщение: Re: [Proposal] Table-level Transparent Data Encryption (TDE) and KeyManagement Service (KMS)