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
