I would love to see the ability to output the help docs in a format that could be dropped into documentation. In Solr we basically cut and paste the -h output into the Reference Guide, it works but it’s ugly and manual. I’ve been experimenting with some tools that let you run a tool, capture the output, and incorporate that into the help docs.
Imagine if I had a "-h —output markdown" that gave a nice table structure? That could then be incorporated directly into the docs and generated at build time. Honestly, if I had to write my own string handling code to actually do the output, but the structure was all there, that would be super helpful. > On Sep 19, 2024, at 7:36 AM, Gary Gregory <garydgreg...@gmail.com> wrote: > > Hi Claude, > > I think it needs to be flexible/complex just enough to support doing what I > mentioned. I like XML because once you have that, you can get anywhere else > with XSL. How do you do transformations in JSON anyway? Has that wheel been > reinvented? JOLT seems not to have gone anywhere. > > Maybe we need a PR to get us started to get done what you need to do. WRT > formats, at least one can be provided as a test to make sure the code is > extensible enough. > > Gary > > > On Thu, Sep 19, 2024, 6:53 AM Claude Warren <cla...@xenei.com> wrote: > >> This could get complex fairly quickly. So a couple of questions: >> >> Q: Do we want to create a new commons project or perhaps expand >> commons-text to contain a simple library for formatting output. If we do >> that we would have to include it in commons-cli which I know is >> undesirable, but if text is small enough it should not be a problem. >> >> Q: Do we want to create/support multiple output formatters (e.g. XML, >> XHMTL, Text, markdown)? >> >> >> >> On Wed, Sep 18, 2024 at 5:40 PM Gary Gregory <garydgreg...@gmail.com> >> wrote: >> >>> If we create something new, it would be nice to have example in tests >> that >>> show rendering to XHTML and XML. This means the abstract superclass >> should >>> not assume console output. A site can use its own CSS for styling. If we >>> are flexible enough we should not need to create yet another thing in >>> the future. >>> >>> Gary >>> >>> On Wed, Sep 18, 2024, 11:23 AM Claude Warren <cla...@xenei.com> wrote: >>> >>>> I think that help formatting really comes down to building a textual >>>> matrix from a list of Options. To do this we need to have several >> things: >>>> >>>> 1. A list of headers (text for the columns in the table) >>>> 2. The minimum and maximum width for each column. (perhaps as a % of >>>> the width) >>>> 3. A method that converts the Option into the columns. >>>> >>>> >>>> Interface TableDef { >>>> String header(); >>>> String footer(); >>>> List<String> columnHeaders(); >>>> int[] minimumColumnSize(); >>>> int[] maximumColumnSize(); >>>> Iterator<List<String>> rows(); >>>> } >>>> >>>> abstract class AbstractHelpFormatter { >>>> int width; >>>> List<TableDef> tables; >>>> >>>> printUsage(PrintWriter writer, String commandLineSyntax) { >>>> // print the command line syntax. >>>> for(TableDef table : tables) { >>>> writer.println(table.header()) >>>> for(String line : >>>> formatColumns(table.minimumColumnSize(), table.maximumColumnSize(), >>>> columnHeaders())) { >>>> writer.println(line); >>>> } >>>> Iterator<List<String>> rows = table.rows(); >>>> while(rows.hasNext()) { >>>> formatColumns(table.minimumColumnSize(), >>>> table.maximumColumnSize(), row.next()).forEach(writer::println); >>>> } >>>> writer.println(table.footer()) >>>> } >>>> } >>>> } >>>> >>>> where formatColumns is a static method in HelpFormatter that will >> produce >>>> a list of Strings necessary to properly display the wrapped columns. >> Any >>>> helper functions for formatColumns() would also be public static so that >>>> they can be reused for other implementations. >>>> >>>> The concrete implementation would be the implementation we currently >> have >>>> adapted to fit this pattern. >>>> >>>> I have code like this in the new RAT code. >>>> >>>> Does this make sense to you? >>>> >>>> Claude >>>> >>>> >>>> >>>> >>>> On Wed, Sep 18, 2024 at 2:57 PM Eric Pugh < >>>> ep...@opensourceconnections.com> wrote: >>>> >>>>> In Solr we added some additional formatting methods to our Tool.java >>>>> interface to help with formatting the various tools that use >> commons-cli: >>>>> >>>>> [image: solr.png] >>>>> >>>>> solr/solr/core/src/java/org/apache/solr/cli/Tool.java at main · >>>>> apache/solr >>>>> < >> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/Tool.java#L34 >>> >>>>> github.com >>>>> < >> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/Tool.java#L34 >>> >>>>> >>>>> < >> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/Tool.java#L34 >>> >>>>> >>>>> PackageTool had a very very custom help output that we didn’t want to >>>>> lose when we redid things, so it has a custom getHeader: >>>>> >>>>> >>>>> >>>>> [image: solr.png] >>>>> >>>>> solr/solr/core/src/java/org/apache/solr/cli/PackageTool.java at main · >>>>> apache/solr >>>>> < >> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PackageTool.java#L251 >>> >>>>> github.com >>>>> < >> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PackageTool.java#L251 >>> >>>>> >>>>> < >> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PackageTool.java#L251 >>> >>>>> >>>>> Whereas CreateTool had a short bit of additional text, and then the >>>>> options: >>>>> >> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/CreateTool.java#L70 >>>>> >>>>> And our PostLogsTool doesn’t use any of those extra formatting helpers: >>>>> >> https://github.com/apache/solr/blob/main/solr/core/src/java/org/apache/solr/cli/PostLogsTool.java >>>>> >>>>> >>>>> I do wish this had been part of commons-cli! >>>>> >>>>> Eric >>>>> >>>>> >>>>> >>>>> On Sep 18, 2024, at 9:52 AM, Gary Gregory <garydgreg...@gmail.com> >>>>> wrote: >>>>> >>>>> Or a new better formatting class? >>>>> >>>>> Gary >>>>> >>>>> On Wed, Sep 18, 2024, 9:45 AM Claude Warren <cla...@xenei.com> wrote: >>>>> >>>>> After more exploration it seems that HelpFormatter is really not >> designed >>>>> to be extended. I will have to rethink this. It may make sense to >> make >>>>> some of the HelpFormatter methods static so that they can be used in >>>>> other >>>>> implementations. >>>>> >>>>> On Wed, Sep 18, 2024 at 9:29 AM Claude Warren <cla...@xenei.com> >> wrote: >>>>> >>>>> Greetings, >>>>> >>>>> I have a case in RAT where we want to append a line to the help text >> when >>>>> the option has multiple arguments or when we have defined a default >>>>> >>>>> value. >>>>> >>>>> >>>>> I have implemented this in a renderOptions() implementation in CLI >> 1.8.0. >>>>> In both cases we use the Option to check for some state and then append >>>>> >>>>> to >>>>> >>>>> the optBuf. >>>>> >>>>> I am now migrating to 1.9.0 and have to do the same thing, but 1.9.0 >> adds >>>>> more functionality to the default renderOptions() method so I have to >>>>> rework my implementation. However, had I not known this was the case, >> I >>>>> would have missed the changes and we would have had some rather >>>>> >>>>> interesting >>>>> >>>>> bugs later. >>>>> >>>>> What I am proposing is a new parameter to renderOptions(). A >>>>> "Optional<String> Function<Option>". If the function returns a String >>>>> >>>>> then >>>>> >>>>> it is appended to the optBuf. >>>>> >>>>> This method would be called near the end of renderOptions. >>>>> >>>>> Thoughts? >>>>> Claude >>>>> >>>>> -- >>>>> LinkedIn: http://www.linkedin.com/in/claudewarren >>>>> >>>>> >>>>> >>>>> -- >>>>> LinkedIn: http://www.linkedin.com/in/claudewarren >>>>> >>>>> >>>>> _______________________ >>>>> *Eric Pugh **| *Founder | OpenSource Connections, LLC | 434.466.1467 | >>>>> http://www.opensourceconnections.com | My Free/Busy >>>>> <http://tinyurl.com/eric-cal> >>>>> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed >>>>> < >> https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw >>> >>>>> This e-mail and all contents, including attachments, is considered to >> be >>>>> Company Confidential unless explicitly stated otherwise, regardless >>>>> of whether attachments are marked as such. >>>>> >>>>> >>>> >>>> -- >>>> LinkedIn: http://www.linkedin.com/in/claudewarren >>>> >>>> --------------------------------------------------------------------- >>>> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org >>>> For additional commands, e-mail: dev-h...@commons.apache.org >>> >>> >> >> -- >> LinkedIn: http://www.linkedin.com/in/claudewarren >> _______________________ Eric Pugh | Founder | OpenSource Connections, LLC | 434.466.1467 | http://www.opensourceconnections.com <http://www.opensourceconnections.com/> | My Free/Busy <http://tinyurl.com/eric-cal> Co-Author: Apache Solr Enterprise Search Server, 3rd Ed <https://www.packtpub.com/big-data-and-business-intelligence/apache-solr-enterprise-search-server-third-edition-raw> This e-mail and all contents, including attachments, is considered to be Company Confidential unless explicitly stated otherwise, regardless of whether attachments are marked as such.