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. -- Ivan Zhakov
