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.
