Re: [Tools-discuss] Single source throughout. (Was creating bis docs automatically)

[Eric Rescorla <[e-mail]>]

On Sat, Mar 4, 2023 at 1:22 AM Jay Daley <[e-mail]> wrote:

>
>
> > On 3 Mar 2023, at 23:59, Martin Thomson <[e-mail]> wrote:
> >
> > The tool Jean suggests is probably more general, but several working
> groups I participate in track changes at AUTH48 so that the source produces
> something indistinguishable from the RFC.  If you do that, the -bis only
> requires picking up the original source.
> >
> > That is a practice I encourage others to follow, if only because it
> treats the publication process as another step in a longer term process of
> integrating feedback and improving a document[1].  A -bis publication is
> merely the obvious next step in that process.
> >
> > In an ideal world, the RPC would be contributing edits to a canonical
> source, from which the occasional publication as RFC is just a snapshot.
> But the diversity of toolchains and sources and practices tends to make
> that difficult.
>
> I disagree and this is where I think we have a rather fundamental
> difference of view that has implications for the whole document production
> process, particularly the current GitHub experiments.
>
> Our document production model is quite clear that authoring and
> publication are two very distinct steps with authors and publishers (i.e.
> the RPC) having different roles and responsibilities. The authors are of
> course responsible for the meaningful content of the documents but, while
> they have a say in the representation in order to ensure the integrity of
> that meaningful content, the RPC is ultimately responsible for the
> representation. There’s a similar division of responsibility as far as the
> language used in our documents. This is a fundamental aspect of us using a
> professional publishing function.
>

> The transfer from authoring to publication is therefore a transfer of
> ownership of the working source from authors to the RPC. This is how every
> other form of professional publishing works - book publishers take the
> author’s manuscript and input it into their publishing system which they
> then work on without backporting changes to the manuscript.
>

I agree that this is common, but it is not in fact universally correct to
say that it
happens in "every other form of professional publishing":

1. It is not unknown to send "camera ready" PDF directly to the publisher
who then publishes
it as-is. I know of several books where this has happened and it used to be
very
common in printed CS conference proceedings, back when such things existed.
I have done this myself, and as I understand, it's still how some (many?)
CS journals work.

2. Even in cases where the final typesetting is done by the publisher, it's
not uncommon for
the publisher to provide all of the editorial (E.g., copy-edit) changes to
the author in the
author's original format (or, in the old days, on paper!), and the author
then accepts or
rejects them, producing a final text (sometimes called the "fair copy")
which is then typeset
and published.

Our process is uniquely inconvenient in that if the authors use MD (or
arguably even
xml2rfc) the RPC does neither of these, leaving us in a situation where the
author
does not have the fair copy and needs to reconstruct it from the RPC's
source.


I understand that authors are surprised at this change of control and feel
> a strong emotional reaction to giving up that ownership and want to
> maintain some ideal of a single start-to-finish source history, but they
> are not publishers and their control and their source control stop when the
> document is sent for publication.  The ‘finish’ of the start-to-finish
> ideal has to be when the document is sent to the publishers, not when it is
> published. We could certainly explain this better to our authors and better
> set their expectations around this. Only recently I suggested to the RPC
> that they rewrite the message they send when the publishing process kicks
> off, to do exactly that.
>

I agree that this is how things currently work, but the question at hand is
how they *ought* to work.

In that vein, I think that we should recognize that traditional publishing
is an activity organized
for the convenience of the publishers, not for the authors. However, in
this case, what we have
is more akin to self-publishing, with the RPC being more like a contract
publisher, and so matters
ought to be arranged for the convenience of the customer, which is to say
the IETF, IAB,
ISE, etc. That is, of course, not the end of the analysis, but suggests
that the question of how
things usually happen is not the right test.


Some might think that a document can basically re-enter the authoring phase
> when someone chooses to write a -bis but again it’s our model that sets the
> structure here. Our model does not have versions of RFCs and so writing a
> -bis is starting a new document and a new source history, not continuing
> the previous one.
>

Much could be said about books, and yet, as noted above, in many book
publishing workflows,
the author is left with a copy of the corrected manuscript.

-Ekr


> Sure, I understand that there is a modern alternative model for developing
> technical standards of living documents, no separate publication
> role/phase, and a single start-to-finish source history, but what we do is
> quite different.
>
> Jay
>
> --
> Jay Daley
> IETF Executive Director
> >
> > Cheers,
> > Martin
> >
> > [1]  A particularly challenging one, as it turns out.  The breadth of
> changes the RPC makes does tend to be quite hard to track.  But it
> generally only takes a few hours, even on a very long document.
> >
> >> On Sat, Mar 4, 2023, at 07:36, Jean Mahoney wrote:
> >> Just thinking out loud -- I think it would helpful for author-tools to
> >> provide an option of starting a bis doc.
> >>
> >> On author-tools, an author could enter the number of the RFC they want
> >> to create a bis draft for, provide a draftname for it, and select a
> file
> >> format (XML or markdown). author-tools (or whatever is behind the
> >> curtain) would then fetch the RFC file from rfc-editor.org, do the
> >> necessary updates (e.g., removing the RFC number), and make a file
> >> available for download.
> >>
> >> I've created an enhancement request:
> >> https://github.com/ietf-tools/ietf-at-ui/issues/152
> >>
> >> Thanks!
> >> Jean
> >>
> >>
> >>> On 3/3/23 2:07 PM, Jean Mahoney wrote:
> >>> Hi Paul,
> >>>
> >>> On 3/3/23 12:58 PM, Paul Hoffman wrote:
> >>>> On 3 Mar 2023, at 10:54, Jean Mahoney wrote:
> >>>>
> >>>>> Converting the file to v3 will remove the warning about
> >>>>> rfc2629-xhtml.ent the next time you run xml2rfc. You don't have to
> >>>>> make any changes to the file before uploading it to
> >>>>> author-tools.ietf.org to convert it.
> >>>> OK, this is useful. I propose that when authors ask the RPC for the
> >>>> last XML because they're making a -bis, that this be suggested to
> them.
> >>> [JM] authors.ietf.org could also provide more info, then the RPC
> could
> >>> provide a pointer to it. I created an issue:
> >>> https://github.com/ietf/authors.ietf.org/issues/56
> >>>
> >>> Thanks!
> >>> Jean
> >>>
> >>>>
> >>>> I can handle this easily from here.
> >>>>
> >>>> --Paul Hoffman
> >>>>
> >>>
> >>> ___________________________________________________________
> >>> Tools-discuss mailing list - [e-mail] -
> >>> https://www.ietf.org/mailman/listinfo/tools-discuss
> >>>
> >>
> >> ___________________________________________________________
> >> Tools-discuss mailing list - [e-mail] -
> >> https://www.ietf.org/mailman/listinfo/tools-discuss
> >
> > ___________________________________________________________
> > Tools-discuss mailing list - [e-mail] -
> https://www.ietf.org/mailman/listinfo/tools-discuss
>
> ___________________________________________________________
> Tools-discuss mailing list - [e-mail] -
> https://www.ietf.org/mailman/listinfo/tools-discuss
>