Bug#526469: manpage missing for sysfs.conf

[Matt Taggart]

On 8/3/22 16:28, Guillem Jover wrote:


What about something like the attached page?


Looks great!
I guess "These file" in the second paragraph should be "These files" to 
be consistent with the first. It's a little confusing since you might be 
talking about sysfs.conf or files in /etc/sysfs.d/... I checked to see 
what sysctl does and they have separate manpages for sysctl.conf and 
sysctl.d, so I guess that's an option too.


Thanks,

--
Matt Taggart
m...@lackof.org

Bug#526469: manpage missing for sysfs.conf

[Guillem Jover]

Hi!

On Wed, 2022-08-03 at 14:50:42 -0700, Matt Taggart wrote:
> Here are some notes about documenting sysfs.conf
> 
> * sysfs(2) is about the syscall and isn't helpful in this context
> * sysfs(5) (in manpages package) explains a little about sysfs, but not how
> to interact with it.
> * The kernel documentation
> https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt is targetted
> at people writing sysfs interfaces and mostly not useful, but mentions that
> interfaces need to be documented in ABI
> https://www.kernel.org/doc/Documentation/ABI/stable/ and that might be
> useful to mention as a place where users can read about how to interact with
> various parts.
> * The default delivered sysfs.conf file has some comments at the top about
> general syntax and examples.
> * should document /etc/sysfs.d/ and how to use it (load order, etc)
> * should maybe explain the difference between sysfs and sysctl
> 
> So I think a sysfs.conf manpage could be pretty simple, mostly the comments
> already in the default file and some pointers to the other places.

Thanks for these notes! A nice start incentive. :)

What about something like the attached page?

Thanks,
Guillem
# sysfs.conf manual page (sysfs.conf.5)
#
# Copyright © 2022 Guillem Jover 
#
# This is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see .

=encoding utf8

=head1 NAME

sysfs.conf - Linux sysfs attributes setting configuration file

=head1 DESCRIPTION

These configuration files can be used to set B attribute values,
modify their file mode or owner, during the system boot.

These file are concerned with the F filesystem and should not be
confused with the F configuration which is concerned
with F filesystem instead.

=head1 FORMAT

The syntax consists on a series of line based directives for F
attributes, those being pathnames within that filesystem, with the
following format:

=over 4

=item I = I

Set I for the F I.

=item B I = I

Set the I for the F I.
Where I is any mode accepted by L.

=item B I = I[:I]

Set the I (and/or I) for the F I.
Where I (and/or I) are any specification accepted by
L.

=back

Leading and trailing spaces, and spaces around the B<=> character are
ignored.

Comments start with a B<#> character until the end of line.
Empty or space-only lines are also ignored.

=head1 FILES

=over

=item F

The main configuration file.
It gets loaded first if readable.

=item F

The optional configuration fragment files.
These get loaded after the main configuration file, if readable,
in glob order.

=back

=head1 EXAMPLES

Always use the powersave CPU frequency governor.

  devices/system/cpu/cpu0/cpufreq/scaling_governor = powersave

Use userspace CPU frequency governor and set initial speed.

  devices/system/cpu/cpu0/cpufreq/scaling_governor = userspace
  devices/system/cpu/cpu0/cpufreq/scaling_setspeed = 60

Set permissions of suspend control file.

  mode power/state = 0660
  owner power/state = root:power

=head1 SEE ALSO

L,
L,
L.

Bug#526469: manpage missing for sysfs.conf

[Matt Taggart]

Here are some notes about documenting sysfs.conf

* sysfs(2) is about the syscall and isn't helpful in this context
* sysfs(5) (in manpages package) explains a little about sysfs, but not 
how to interact with it.
* The kernel documentation 
https://www.kernel.org/doc/Documentation/filesystems/sysfs.txt is 
targetted at people writing sysfs interfaces and mostly not useful, but 
mentions that interfaces need to be documented in ABI 
https://www.kernel.org/doc/Documentation/ABI/stable/ and that might be 
useful to mention as a place where users can read about how to interact 
with various parts.
* The default delivered sysfs.conf file has some comments at the top 
about general syntax and examples.

* should document /etc/sysfs.d/ and how to use it (load order, etc)
* should maybe explain the difference between sysfs and sysctl

So I think a sysfs.conf manpage could be pretty simple, mostly the 
comments already in the default file and some pointers to the other places.


--
Matt Taggart
m...@lackof.org

Bug#526469: manpage missing for sysfs.conf

[Michael Stapelberg]

Package: sysfsutils
Version: 2.1.0-5
Severity: normal

Manpage for sysfs.conf(5) is missing.

-- System Information:
Debian Release: squeeze/sid
  APT prefers testing
  APT policy: (990, 'testing'), (600, 'unstable')
Architecture: amd64 (x86_64)

Kernel: Linux 2.6.29-6 (SMP w/2 CPU cores)
Locale: LANG=C, LC_CTYPE=de_DE.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/bash

Versions of packages sysfsutils depends on:
ii  libc6 2.9-4  GNU C Library: Shared libraries
ii  libsysfs2 2.1.0-5interface library to sysfs

sysfsutils recommends no packages.

sysfsutils suggests no packages.

-- no debconf information



-- 
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org