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
>
