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.

Reply via email to