Hello, I'd suggest merging all pending INSTALL-related changes first (i.e., before converting the document to Markdown). That would be easier as we'd avoid extra work and unnecessary merge conflicts.
-- With best regards, Pavel Lyalyakin On Sat, 7 Nov 2026 at 16:28 Daniel Sahlberg <[email protected]> wrote: > 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 > > > > > >
