Keep us posted! I would love to contribute a Markdown format.
> On Sep 23, 2024, at 7:20 AM, Claude Warren <cla...@xenei.com> wrote:
>
> I have a system that mostly works. But implementing XML output requires
> StringEscapeUtils from commons-text. I know we are reluctant to include
> other packages. So my thought is that we provide the XML option as an
> example so that we don't include the commons-text in the package.
>
> My strategy is to separate the formatting into 2 components.
>
> OptionFormat -- Defines the output format for options. What gets displayed
> on the syntax options, and the option table contents. I have a default
> implementation that provides the same data as the current HelpFormatter one.
>
> OutputFormat -- Defines the serialization format for the OptionFormat. I
> have two implementations. Text which outputs the current format, XML for
> xml output option format data, and APT format in an example.
>
> My next step is to verify that I can implement the Rat help system.
>
>
>
> Imp
>
> On Fri, Sep 20, 2024 at 12:47 PM Gary Gregory <garydgreg...@gmail.com>
> wrote:
>
>> Looking forward to it 😀
>>
>> Gary
>>
>> On Fri, Sep 20, 2024, 3:56 AM Claude Warren <cla...@xenei.com> wrote:
>>
>>> I have been working on Rat and have a set of classes that output
>> markdown.
>>> I think I can make CLI HelpFormtter system take a class to output the
>> data
>>> in any given format.
>>>
>>> What rat is doing now is writing help to a file and using APT format to
>>> include that using Velocity.
>>>
>>> Gary's point that XML provides broad support, and Eric's point about
>>> markdown and the general case for text seems to indicate that
>> applications
>>> need a way to specify how to format the data, as well as access to the
>>> current tooling that makes generating/aggregating the text easier. I
>> will
>>> work on this and create a pull request where we can discuss how it works.
>>>
>>> On Thu, Sep 19, 2024 at 1:00 PM Eric Pugh <
>> ep...@opensourceconnections.com
>>>>
>>> wrote:
>>>
>>>> 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.
>>>>
>>>>
>>>
>>> --
>>> 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 <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.
