You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@lucene.apache.org by "dweiss (via GitHub)" <gi...@apache.org> on 2026/08/30 08:39:15 UTC
[PR] Convert help files to markdown [lucene]
dweiss opened a new pull request, #16584:
URL: https://github.com/apache/lucene/pull/16584
This converts help files to markdown and keeps their gradle `helpXyz` tasks by reformatting gradle to plain text using flexmark. The patch is LLM generated but it looks reasonable to me.
I may polish some of the details - I'm travelling today - but I think it's good as a PoC that it's doable (and valuable)?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "dweiss (via GitHub)" <gi...@apache.org>.
dweiss commented on PR #16584:
URL: https://github.com/apache/lucene/pull/16584#issuecomment-5469442971
It is a bit weird - I had eclint locally and ran -fix. And it was passing locally but not remotely. I'm travelling today but something went sideways there - I'll try to see what once I get back home.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "dweiss (via GitHub)" <gi...@apache.org>.
dweiss commented on PR #16584:
URL: https://github.com/apache/lucene/pull/16584#issuecomment-5470328102
I've played with some colorized output from gradle but I don't think it makes sense. A lot of code added for little gain. I'd leave this as is and merge.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "rmuir (via GitHub)" <gi...@apache.org>.
rmuir commented on PR #16584:
URL: https://github.com/apache/lucene/pull/16584#issuecomment-5470715080
@dweiss yeah maybe an issue with `-fix`. I didn't use that. I opened up in editor and fixed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "dweiss (via GitHub)" <gi...@apache.org>.
dweiss commented on code in PR #16584:
URL: https://github.com/apache/lucene/pull/16584#discussion_r3893444427
##########
help/dependencies.md:
##########
@@ -0,0 +1,128 @@
+# Dependencies
+
+Each gradle project can have multiple (named) "configurations" and each configuration can have dependencies attached
+to it.
+
+There are some standard conventions so, for example, the Java plugin adds standard configurations such as `api`,
+`implementation`, `testImplementation` and others. These configurations can also inherit from each other; more about
+this topic can be found here:
+
+- <https://docs.gradle.org/current/userguide/dependency_management_for_java_projects.html#dependency_management_for_java_projects>
+- <https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_separation>
+- <https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_plugin_and_dependency_management>
+
+Lucene uses the following configurations and attach project dependencies to them:
+
+- `moduleApi` - makes the dependency available to main classes, tests and any other modules importing the project (exportable dependency),
+- `moduleImplementation` - makes the dependency available to main classes, tests but will *not* export the dependency to other modules (so their compilation classpath won't contain it).
+- `moduleTestImplementation` - makes the dependency available for test classes only.
+
+The `module` prefix is used to distinguish configurations which apply to modular builds, compared to the regular
+classpath-configurations defined by gradle's java module. Some Lucene modules may define regular classpath entries to
+bypass the limitations of the module system (or gradle's).
+
+## Adding a library dependency
+
+Lucene dependencies and their versions are managed globally using version catalogs (in `gradle/libs.versions.toml`)
+<https://docs.gradle.org/current/userguide/platforms.html>.
+
+Let's say we wish to add a dependency on library `foo.bar:baz` in version 1.2 to `:lucene:core`. Let's assume this
+library is only used internally by the project. The `:lucene:core` project is configured by `lucene/core/build.gradle`,
+so we add (or modify) the dependency block as follows:
+
+```groovy
+dependencies {
+ moduleImplementation deps.baz
+}
+```
+
+The `moduleImplementation` here is a named configuration explained in the section above. The `deps.baz` refers to the
+version catalog named `deps`, in which the dependency `baz` should be declared. If this is the first reference to this
+library, then we have to add it to `versions.toml` catalog: the version goes under the `versions` and module
+coordinates under the `libraries` section:
+
+```toml
+[versions]
+baz = "1.2"
+...
+[libraries]
+baz = { module = "foo.bar:baz", version.ref = "baz" }
+```
+
+The version defined in the `versions` section is the preferred version of the library we wish to use. Finally, run
+tidy to sort all entries in `libs.versions.toml`:
+
+```shell
Review Comment:
I'll switch these to bash.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "dweiss (via GitHub)" <gi...@apache.org>.
dweiss commented on code in PR #16584:
URL: https://github.com/apache/lucene/pull/16584#discussion_r3888901284
##########
build-tools/build-infra/src/main/java/org/apache/lucene/gradle/plugins/misc/MarkdownToText.java:
##########
@@ -0,0 +1,118 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.lucene.gradle.plugins.misc;
+
+import com.vladsch.flexmark.ast.BlockQuote;
+import com.vladsch.flexmark.ast.FencedCodeBlock;
+import com.vladsch.flexmark.ast.HardLineBreak;
+import com.vladsch.flexmark.ast.Heading;
+import com.vladsch.flexmark.ast.IndentedCodeBlock;
+import com.vladsch.flexmark.ast.Link;
+import com.vladsch.flexmark.ast.LinkNodeBase;
+import com.vladsch.flexmark.ast.ListBlock;
+import com.vladsch.flexmark.ast.OrderedList;
+import com.vladsch.flexmark.ast.Paragraph;
+import com.vladsch.flexmark.ast.SoftLineBreak;
+import com.vladsch.flexmark.ast.Text;
+import com.vladsch.flexmark.ast.ThematicBreak;
+import com.vladsch.flexmark.parser.Parser;
+import com.vladsch.flexmark.util.ast.Node;
+import com.vladsch.flexmark.util.sequence.Escaping;
+
+/** Renders markdown as plain text for console output (flexmark AST walk, paragraphs wrapped). */
+final class MarkdownToText {
Review Comment:
This is simple and plain but keeps the dependencies reasonable. People can always use local tools if they wish (glow, pandoc).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "dweiss (via GitHub)" <gi...@apache.org>.
dweiss commented on PR #16584:
URL: https://github.com/apache/lucene/pull/16584#issuecomment-5470278919
On commit 6de0b743abfa137e082d88563d5e778514e6350a, eclint fails with:
```
help/dependencies.md:
17:3: indentation size doesn't match expected 4, got 2
(exportable dependency),
19:3: indentation size doesn't match expected 4, got 2
to other modules (so their compilation classpath won't contain it).
help/git.md:
7:3: indentation size doesn't match expected 4, got 2
those commits): <https://eagain.net/articles/git-for-computer-scientists/>
```
but adding `-fix` doesn't seem to recover from the problem - it runs, doesn't print any error, subsequent eclint still prints the warning.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "rmuir (via GitHub)" <gi...@apache.org>.
rmuir commented on PR #16584:
URL: https://github.com/apache/lucene/pull/16584#issuecomment-5470148196
> It is a bit weird - I had eclint locally and ran -fix. And it was passing locally but not remotely. I'm travelling today but something went sideways there - I'll try to see what once I get back home.
We can think about disabling it for filetypes where we have better tools that take care of things? For example we have a markdown linter/formatter now.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "uschindler (via GitHub)" <gi...@apache.org>.
uschindler commented on PR #16584:
URL: https://github.com/apache/lucene/pull/16584#issuecomment-5471795024
Is there no standard MD to TEXT converter provided with flexmark? If yes, we may remove the code. Haven't checked yet, but I have the feeling it may be there aready.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "uschindler (via GitHub)" <gi...@apache.org>.
uschindler commented on PR #16584:
URL: https://github.com/apache/lucene/pull/16584#issuecomment-5474538671
> Is there no standard MD to TEXT converter provided with flexmark? If yes, we may remove the code. Haven't checked yet, but I have the feeling it may be there aready.
There is also https://github.com/vsch/flexmark-java/issues/63 available, but it does not properly handle newlines in a good way, so possibly your solution is better for a console application.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "rmuir (via GitHub)" <gi...@apache.org>.
rmuir commented on code in PR #16584:
URL: https://github.com/apache/lucene/pull/16584#discussion_r3893240874
##########
help/dependencies.md:
##########
@@ -0,0 +1,128 @@
+# Dependencies
+
+Each gradle project can have multiple (named) "configurations" and each configuration can have dependencies attached
+to it.
+
+There are some standard conventions so, for example, the Java plugin adds standard configurations such as `api`,
+`implementation`, `testImplementation` and others. These configurations can also inherit from each other; more about
+this topic can be found here:
+
+- <https://docs.gradle.org/current/userguide/dependency_management_for_java_projects.html#dependency_management_for_java_projects>
+- <https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_separation>
+- <https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_plugin_and_dependency_management>
+
+Lucene uses the following configurations and attach project dependencies to them:
+
+- `moduleApi` - makes the dependency available to main classes, tests and any other modules importing the project (exportable dependency),
+- `moduleImplementation` - makes the dependency available to main classes, tests but will *not* export the dependency to other modules (so their compilation classpath won't contain it).
+- `moduleTestImplementation` - makes the dependency available for test classes only.
+
+The `module` prefix is used to distinguish configurations which apply to modular builds, compared to the regular
+classpath-configurations defined by gradle's java module. Some Lucene modules may define regular classpath entries to
+bypass the limitations of the module system (or gradle's).
+
+## Adding a library dependency
+
+Lucene dependencies and their versions are managed globally using version catalogs (in `gradle/libs.versions.toml`)
+<https://docs.gradle.org/current/userguide/platforms.html>.
+
+Let's say we wish to add a dependency on library `foo.bar:baz` in version 1.2 to `:lucene:core`. Let's assume this
+library is only used internally by the project. The `:lucene:core` project is configured by `lucene/core/build.gradle`,
+so we add (or modify) the dependency block as follows:
+
+```groovy
+dependencies {
+ moduleImplementation deps.baz
+}
+```
+
+The `moduleImplementation` here is a named configuration explained in the section above. The `deps.baz` refers to the
+version catalog named `deps`, in which the dependency `baz` should be declared. If this is the first reference to this
+library, then we have to add it to `versions.toml` catalog: the version goes under the `versions` and module
+coordinates under the `libraries` section:
+
+```toml
+[versions]
+baz = "1.2"
+...
+[libraries]
+baz = { module = "foo.bar:baz", version.ref = "baz" }
+```
+
+The version defined in the `versions` section is the preferred version of the library we wish to use. Finally, run
+tidy to sort all entries in `libs.versions.toml`:
+
+```shell
Review Comment:
I think all these `shell`'s should be changed to explicit `sh`, `bash`, or `zsh`, so that there's a language to highlight. Otherwise you don't get any or correct syntax highlighting. I can clean it up afterwards though.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "dweiss (via GitHub)" <gi...@apache.org>.
dweiss commented on code in PR #16584:
URL: https://github.com/apache/lucene/pull/16584#discussion_r3893457484
##########
help/publishing.md:
##########
@@ -0,0 +1,145 @@
+# Distribution and artifact publishing
+
+See all distribution-related tasks by running:
+
+```shell
+gradlew tasks --group distribution
+```
+
+## Maven
+
+To publish Lucene Maven artifacts to a local `~/.m2` repository, run:
+
+```shell
+gradlew mavenToLocal
+```
+
+To publish Lucene Maven artifacts to Apache repositories (CI or release manager's job, typically!), run:
+
+```shell
+gradlew mavenToApacheSnapshots -PasfNexusUsername= -PasfNexusPassword=
+gradlew mavenToApacheReleases -PasfNexusUsername= -PasfNexusPassword= [optional signing options]
+```
+
+See artifact signing section below if you plan to use `mavenToApacheReleases`.
+
+It is a good idea to avoid passing passwords on command line. CI jobs have these properties saved in
+`~/.gradle/gradle.properties` - this way they are read automatically.
+
+Apache Releases repository will not accept snapshots.
+
+## Release (distribution) artifacts
+
+To collect all release artifacts, and optionally sign them, run:
+
+```shell
+gradlew assembleRelease [optional signing options]
+```
+
+All distribution artifacts will be placed under:
+
+```text
+lucene/distribution/build/release
+```
+
+Artifact signing is optional (but required if you're really making a release).
+
+## Artifact signing
+
+Certain tasks may optionally sign artifacts or require artifacts to be signed:
+
+- `assembleRelease`
+- `mavenToApacheReleases`
+
+Signing can be enabled by adding the `-Psign` option, for example:
+
+```shell
+gradlew assembleRelease mavenToApacheReleases -Psign
+```
+
+By default, gradle uses a Java-based implementation of PGP for signing, which requires several `signing.*` properties
+via either `~/.gradle/gradle.properties` or command-line options:
+
+<https://docs.gradle.org/current/userguide/signing_plugin.html#sec:signatory_credentials>
+
+An example full command-line that assembles signed artifacts could look like this:
+
+```shell
+gradlew assembleRelease mavenToApacheReleases -Psign -Psigning.keyId=... -Psigning.password=... -Psigning.secretKeyRingFile=...
+```
+
+The keyId is the last 8 digits of your key (`gpg -k` will print your keys). Gradle documentation has more options of
+secure passing of private key information and passwords.
+
+## Artifact signing using an external GPG with GPG Agent
+
+You can use an external GPG command to deal with signing artifacts, without needing to give gradle your passphrase, by
+adding a `-PuseGpg=true` option, but this changes the properties you must specify:
+
+For gpg2:
+
+```shell
+gradlew [tasks] -Psign -PuseGpg=true -Psigning.gnupg.keyName=...
+```
+
+For gpg:
+
+```shell
+gradlew [tasks] -Psign -PuseGpg=true -Psigning.gnupg.keyName=... -Psigning.gnupg.useLegacyGpg=true
+```
+
+The keyName is the last 8 digits of your key (`gpg -k` will print your keys).
+
+There are additional (optional) `signing.gnupg.*` properties which exist that may be useful/necessary in your system:
+
+```properties
+signing.gnupg.useLegacyGpg=true # Changes the default executable from `gpg2` to `gpg` and explicitly sets `--use-agent`
+signing.gnupg.executable=gpg # Allows explicit control over what command executable used (ex: `gpg2`, `gpg`, `gpg.exe`, etc...)
+signing.gnupg.homeDir=/tmp/gnupg-home # overrides GnuPG's default home directory (ex: `~/.gnupg/`)
+signing.gnupg.optionsFile=/tmp/gnupg-home/my.conf # overrides GnuPG's default configuration file
+signing.gnupg.passphrase=... # Provide your passphrase to gradle to hand off to gpg. *NOT RECOMMENDED*, see below.
+```
Review Comment:
Applied both. Well spotted.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "dweiss (via GitHub)" <gi...@apache.org>.
dweiss commented on PR #16584:
URL: https://github.com/apache/lucene/pull/16584#issuecomment-5476022429
Correct - I also liked the fact that claude reused flexmark for the conversion. The resulting class is small enough (and good enough!) that I didn't think it needs any changes. Command-line tools like glow (https://github.com/charmbracelet/glow) can be used for fancy cli-rendering with URLs, colors, etc. They need to be installed manually but they do a great job.
For our needs, I think the code Claude generated is more than fine (compared to plain-text format we get linting, github markdown rendering, etc.).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "rmuir (via GitHub)" <gi...@apache.org>.
rmuir commented on code in PR #16584:
URL: https://github.com/apache/lucene/pull/16584#discussion_r3893427502
##########
help/publishing.md:
##########
@@ -0,0 +1,145 @@
+# Distribution and artifact publishing
+
+See all distribution-related tasks by running:
+
+```shell
+gradlew tasks --group distribution
+```
+
+## Maven
+
+To publish Lucene Maven artifacts to a local `~/.m2` repository, run:
+
+```shell
+gradlew mavenToLocal
+```
+
+To publish Lucene Maven artifacts to Apache repositories (CI or release manager's job, typically!), run:
+
+```shell
+gradlew mavenToApacheSnapshots -PasfNexusUsername= -PasfNexusPassword=
+gradlew mavenToApacheReleases -PasfNexusUsername= -PasfNexusPassword= [optional signing options]
+```
+
+See artifact signing section below if you plan to use `mavenToApacheReleases`.
+
+It is a good idea to avoid passing passwords on command line. CI jobs have these properties saved in
+`~/.gradle/gradle.properties` - this way they are read automatically.
+
+Apache Releases repository will not accept snapshots.
+
+## Release (distribution) artifacts
+
+To collect all release artifacts, and optionally sign them, run:
+
+```shell
+gradlew assembleRelease [optional signing options]
+```
+
+All distribution artifacts will be placed under:
+
+```text
+lucene/distribution/build/release
+```
+
+Artifact signing is optional (but required if you're really making a release).
+
+## Artifact signing
+
+Certain tasks may optionally sign artifacts or require artifacts to be signed:
+
+- `assembleRelease`
+- `mavenToApacheReleases`
+
+Signing can be enabled by adding the `-Psign` option, for example:
+
+```shell
+gradlew assembleRelease mavenToApacheReleases -Psign
+```
+
+By default, gradle uses a Java-based implementation of PGP for signing, which requires several `signing.*` properties
+via either `~/.gradle/gradle.properties` or command-line options:
+
+<https://docs.gradle.org/current/userguide/signing_plugin.html#sec:signatory_credentials>
+
+An example full command-line that assembles signed artifacts could look like this:
+
+```shell
+gradlew assembleRelease mavenToApacheReleases -Psign -Psigning.keyId=... -Psigning.password=... -Psigning.secretKeyRingFile=...
+```
+
+The keyId is the last 8 digits of your key (`gpg -k` will print your keys). Gradle documentation has more options of
+secure passing of private key information and passwords.
+
+## Artifact signing using an external GPG with GPG Agent
+
+You can use an external GPG command to deal with signing artifacts, without needing to give gradle your passphrase, by
+adding a `-PuseGpg=true` option, but this changes the properties you must specify:
+
+For gpg2:
+
+```shell
+gradlew [tasks] -Psign -PuseGpg=true -Psigning.gnupg.keyName=...
+```
+
+For gpg:
+
+```shell
+gradlew [tasks] -Psign -PuseGpg=true -Psigning.gnupg.keyName=... -Psigning.gnupg.useLegacyGpg=true
+```
+
+The keyName is the last 8 digits of your key (`gpg -k` will print your keys).
+
+There are additional (optional) `signing.gnupg.*` properties which exist that may be useful/necessary in your system:
+
+```properties
+signing.gnupg.useLegacyGpg=true # Changes the default executable from `gpg2` to `gpg` and explicitly sets `--use-agent`
+signing.gnupg.executable=gpg # Allows explicit control over what command executable used (ex: `gpg2`, `gpg`, `gpg.exe`, etc...)
+signing.gnupg.homeDir=/tmp/gnupg-home # overrides GnuPG's default home directory (ex: `~/.gnupg/`)
+signing.gnupg.optionsFile=/tmp/gnupg-home/my.conf # overrides GnuPG's default configuration file
+signing.gnupg.passphrase=... # Provide your passphrase to gradle to hand off to gpg. *NOT RECOMMENDED*, see below.
+```
Review Comment:
Java Properties files don't support trailing comments, this sometimes gets highlighted incorrectly. we should move these to line comments above each thing they are documenting.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "dweiss (via GitHub)" <gi...@apache.org>.
dweiss merged PR #16584:
URL: https://github.com/apache/lucene/pull/16584
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org
Re: [PR] Convert help files to markdown [lucene]
Posted by "uschindler (via GitHub)" <gi...@apache.org>.
uschindler commented on code in PR #16584:
URL: https://github.com/apache/lucene/pull/16584#discussion_r3890779248
##########
build-tools/build-infra/src/main/java/org/apache/lucene/gradle/plugins/misc/MarkdownToText.java:
##########
@@ -0,0 +1,118 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.lucene.gradle.plugins.misc;
+
+import com.vladsch.flexmark.ast.BlockQuote;
+import com.vladsch.flexmark.ast.FencedCodeBlock;
+import com.vladsch.flexmark.ast.HardLineBreak;
+import com.vladsch.flexmark.ast.Heading;
+import com.vladsch.flexmark.ast.IndentedCodeBlock;
+import com.vladsch.flexmark.ast.Link;
+import com.vladsch.flexmark.ast.LinkNodeBase;
+import com.vladsch.flexmark.ast.ListBlock;
+import com.vladsch.flexmark.ast.OrderedList;
+import com.vladsch.flexmark.ast.Paragraph;
+import com.vladsch.flexmark.ast.SoftLineBreak;
+import com.vladsch.flexmark.ast.Text;
+import com.vladsch.flexmark.ast.ThematicBreak;
+import com.vladsch.flexmark.parser.Parser;
+import com.vladsch.flexmark.util.ast.Node;
+import com.vladsch.flexmark.util.sequence.Escaping;
+
+/** Renders markdown as plain text for console output (flexmark AST walk, paragraphs wrapped). */
+final class MarkdownToText {
Review Comment:
That uses the same dependencies as the Markdown2Html code we use for the HTML documentation, so this fits perfectly.
Maybe using the new Markdown files we can also provide more files to the official documentation generated with Javadocs. Nice!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org