Re: [RESEND PATCH v5 1/1] docs: driver-api: virtio: virtio on Linux

[Cornelia Huck <cohuck@redhat.com>]

On Mon, Oct 10 2022, "Michael S. Tsirkin" <mst@redhat.com> wrote:

> On Mon, Oct 10, 2022 at 03:43:46PM +0200, Cornelia Huck wrote:
>> On Mon, Oct 10 2022, Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>> 
>> > On Mon, Oct 10, 2022 at 08:43:59AM +0200, Ricardo Cañuelo wrote:
>> >> +
>> >> +References
>> >> +==========
>> >> +
>> >> +_`[1]` Virtio Spec v1.2:
>> >> +https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html
>> >> +
>> >> +Check for later versions of the spec as well.
>> >> +
>> >
>> > The version checking should be made comment (not visible on the output):
>> >
>> > ---- >8 ----
>> > diff --git a/Documentation/driver-api/virtio/virtio.rst b/Documentation/driver-api/virtio/virtio.rst
>> > index 70b3aa6bcf5518..4f3abbec4e8b2c 100644
>> > --- a/Documentation/driver-api/virtio/virtio.rst
>> > +++ b/Documentation/driver-api/virtio/virtio.rst
>> > @@ -134,7 +134,7 @@ References
>> >  _`[1]` Virtio Spec v1.2:
>> >  https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html
>> >  
>> > -Check for later versions of the spec as well.
>> > +.. Check for later versions of the spec as well.
>> >  
>> >  _`[2]` Virtqueues and virtio ring: How the data travels
>> >  https://www.redhat.com/en/blog/virtqueues-and-virtio-ring-how-data-travels
>> >
>> >> diff --git a/Documentation/driver-api/virtio/writing_virtio_drivers.rst b/Documentation/driver-api/virtio/writing_virtio_drivers.rst
>> >> new file mode 100644
>> >> index 000000000000..e14c58796d25
>> >> --- /dev/null
>> >> +++ b/Documentation/driver-api/virtio/writing_virtio_drivers.rst
>> >> <snipped>...
>> >> +References
>> >> +==========
>> >> +
>> >> +_`[1]` Virtio Spec v1.2:
>> >> +https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html
>> >> +
>> >> +Check for later versions of the spec as well.
>> >
>> > Same reply.
>> 
>> I don't think we should hide that in a comment -- unless you want to
>> update this file every time a new version of the virtio spec gets
>> released.
>
> What do you suggest? Just http://docs.oasis-open.org/virtio/virtio/ ?

That one is ugly, as it is just a directory listing... my preference is
to link to the latest version at the time of writing, and mentioning
that there may be later versions available, i.e. what the patch does
right now.

_______________________________________________
Virtualization mailing list
Virtualization@lists.linux-foundation.org
https://lists.linuxfoundation.org/mailman/listinfo/virtualization