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. -- With best regards, Pavel Lyalyakin
