Den tors 5 nov. 2026 kl 23:55 skrev Pavel Lyalyakin via dev < [email protected]>:
> > > On Thu, 5 Nov 2026 at 15:12, Ivan Zhakov via dev < > [email protected]> wrote: > >> On Wed, 4 Nov 2026 at 19:34, Branko Čibej via dev < >> [email protected]> wrote: >> >>> On 4. 11. 2026 18:18, Ivan Zhakov via dev wrote: >>> >>> On Mon, 18 May 2026 at 02:10, Nathan Hartman <[email protected]> >>> wrote: >>> >>>> On Sun, May 17, 2026 at 11:18 AM Daniel Sahlberg < >>>> [email protected]> wrote: >>>> >>>>> Den sön 17 maj 2026 kl 14:56 skrev Timofei Zhakov <[email protected]>: >>>>> > >>>>> > On Sat, May 16, 2026 at 9:47 PM Daniel Sahlberg < >>>>> [email protected]> wrote: >>>>> >> >>>>> >> Den lör 16 maj 2026 kl 20:07 skrev Nathan Hartman < >>>>> [email protected]>: >>>>> >> > >>>>> >> > On Sat, May 16, 2026 at 12:12 PM <[email protected]> wrote: >>>>> >> >> >>>>> >> >> Author: rinrab >>>>> >> >> Date: Sat May 16 16:12:46 2026 >>>>> >> >> New Revision: 1934265 >>>>> >> >> >>>>> >> >> Log: >>>>> >> >> * INSTALL >>>>> >> >> (cmake): Don't mention that cmake is a new addition "available >>>>> only in trunk" >>>>> >> >> and slightly improve writing style. Add a note that gen-make >>>>> is not needed >>>>> >> >> for tar-balls. >>>>> >> >> >>>>> >> >> Modified: >>>>> >> >> subversion/trunk/INSTALL >>>>> >> >> >>>>> >> >> Modified: subversion/trunk/INSTALL >>>>> >> >> >>>>> ============================================================================== >>>>> >> >> --- subversion/trunk/INSTALL Sat May 16 16:11:51 2026 >>>>> (r1934264) >>>>> >> >> +++ subversion/trunk/INSTALL Sat May 16 16:12:46 2026 >>>>> (r1934265) >>>>> >> >> @@ -1194,9 +1194,8 @@ II. INSTALLATION >>>>> >> >> F. Building using CMake >>>>> >> >> -------------------- >>>>> >> >> >>>>> >> >> - Get the sources, either a release tarball or by checking >>>>> out the >>>>> >> >> - official repository. The CMake build system currently >>>>> only exists in >>>>> >> >> - /trunk and it will be included in the 1.15 release. >>>>> >> >> + Get the sources, either from a release tarball or by >>>>> checking out the >>>>> >> >> + official repository. >>>>> >> >> >>>>> >> >> The process for building on Unix and Windows is the same. >>>>> >> >> >>>>> >> >> @@ -1204,6 +1203,9 @@ II. INSTALLATION >>>>> >> >> $ cmake -B out [build options] >>>>> >> >> $ cmake --build out >>>>> >> >> >>>>> >> >> + Note: If you're using the tar-ball distribution, the >>>>> first gen-make step >>>>> >> >> + can be skipped. >>>>> >> >> + >>>>> >> >> "out" in the commands above is the build directory used >>>>> by CMake. >>>>> >> >> >>>>> >> >> Build options can be added, for example: >>>>> >> > >>>>> >> > >>>>> >> > >>>>> >> > Oh, thank you for doing that! >>>>> >> > >>>>> >> > In r1934271 I added a couple of sentences at the start of section >>>>> E >>>>> >> > (building on Windows) to point out the new CMake build. >>>>> >> > >>>>> >> > In r1934272 I nominated both (as a group) for backport to the >>>>> 1.15.x >>>>> >> > branch. >>>>> >> > >>>>> >> > Cheers, >>>>> >> > Nathan >>>>> >> > >>>>> >> >>>>> >> You beat me to it! There was one more revision by Timofei and I >>>>> made a >>>>> >> minor adjustment myself and voted for this all. >>>>> > >>>>> > >>>>> > Thanks guys! >>>>> > >>>>> > I will vote for the backport. Also I guess there are some extra >>>>> nominations that I didn't review yet. >>>>> > >>>>> > Also we currently have that the INSTALL is pretty massive and hard >>>>> for a person to parse. Some stuff there is rather outdated. There are a >>>>> lot >>>>> of notes about copying random DLLs, etc. I think we might consider >>>>> reorganising this document. For example, make it so we have a primary way >>>>> to approach build that consists of './configure ; make' / 'cmake -B out ; >>>>> cmake --build out' with dependencies from system packages and then go >>>>> through some advanced configurations. I think it would be something that a >>>>> user would most likely first look for. >>>>> >>>>> Yes, that would be really good. The Windows build instructions are a >>>>> mess and I have never quite managed to make them work. I also have a >>>>> strong feeling they are outdated, for example they only Apache Httpd >>>>> 2.0 and 2.2 is still a "FIXME". >>>>> >>>>> Cheers, >>>>> Daniel >>>>> >>>> >>>> >>>> True, INSTALL has grown quite complex and the (non-CMake) Windows >>>> procedure (section E) is known to be dated. >>>> >>>> There was a discussion about this in 2020 where Johan and others shared >>>> notes/corrections [1]. >>>> >>>> Thinking out loud: >>>> >>>> Should we remove section E entirely and only document the CMake >>>> procedure for Windows? Maybe for 1.16? >>>> >>>> One good thing about section E is the list of dependencies and required >>>> software. The CMake procedure only mentions Visual Studio and vcpkg--are >>>> those enough to build the whole stack? >>>> >>>> One more thought: it seems many projects like to use Markdown for their >>>> docs nowadays. My only complaint about Markdown: there isn't a definitive >>>> standard; there are different flavors. But putting that aside, would we >>>> want our docs in Markdown format? Would that make them easier to read and >>>> navigate? >>>> >>>> I am +1 to convert INSTALL to INSTALL.md. >>> >>> Current INSTALL is very hard to maintain. For example after r1940037 >>> section C should be removed. But to do this we need to renumber to all >>> document and check all the links. It's time consuming and error-prone >>> operation. >>> >>> >>> >>> I don't see how changing the format of the file will make maintaining it >>> any easier. >>> >>> In plain text it's hard to maintain section links when some section is >> added or removed, because: >> 1. All sections after added/removed section have to be renumbered. >> 2. All section links need to be updated, which is quite error-prone. >> >> In markdown (2) can be solved by using named section links. For one >> technically we might want to drop section numbering because there would be >> section links. >> > > As I've recently (re)moved several sections in INSTALL, I can confirm that > it's not only time consuming and error prone, but just painful. Manually > tracking which lettered/numbered sections or references have to be updated > due to a structural change is a hard work when done manually. But that's > only one side of the problem. > > Another side is that it's hard for a reader to use these references in the > document. As a reader, when I see "... II.A.2 ..." "... (see section II.B). > ..." in a plain text document, I can use Ctrl-F in an attempt to find these > sections. But this won't work well because I have to first search for II, > then scroll up or down a bit to find the section I need. A rendered > markdown with section links would help in this case. > > All things considered I think it makes sense to migrate INSTALL to Markdown, removing the numbering of sections and instead using named section links as suggested by Ivan. Is it better to do this before or after merging the BDB branch? I think Ivan did some changes to INSTALL there. Kind regards, Daniel
