Outdated documentation

This page is out of date. Please use the main navigation to find the latest documentation.

About

kfv.el --- Major mode to help check freedom of the Linux kernel

Note

Note: there is a project for this up at https://gna.org/projects/pfv-mode - version 0.8 is available from there. Also, there is a very useful 9 minute Ogg Theora video on how kfv.el is used.

 Copyright (C) 2008 Bake Timmons

 Authors: Bake Timmons <b3timmons@speedymail.org>
 Created: 4 July 2008
 Version: 0.8

 This file is not part of GNU Emacs.

 This program 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 3, or (at
 your option) any later version.

 This program 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 GNU Emacs see the file COPYING.  If not, write to the
 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 Boston, MA 02110-1301, USA.

Commentary

KFV Mode generates a "KFV file" that the user edits with a few values based on viewing some Linux kernel source files within a given directory. After editing, the user can issue a few keyboard commands to automatically generate and upload the appropriate files to the wiki web site of the gNewSense project.

Directions

1. Load this file. One way to do this is by running M-x load-file ("M-x" means either "press the Escape key, release, then press x" or "hold down the Alt key and then press x") and then giving the complete path to this file, such as ~/kfv.el or /usr/local/etc/kfv.el, to the load-file command.

You also can do some optional things. This file can be compiled once and then the compiled version (kfv.elc) loaded instead for more speed. Also, many things can be customized. Whenever kfv.el or kfv.elc has already been loaded, you can run M-x customize, and in the Applications->KFV category there are some easy customizations requiring no programming. E.g., you can modify some values for your preferred license choice shortcuts.

2. Do this step only once when first using a higher version of kfv.el than you have in the past:

 Run M-x kfv-update-kfv

(There is no need to do this step again until you try an even higher version of kfv.el in the future it is only for upgrading.)

3. Run M-x kfv-start to start KFV Mode.

4. Enter appropriate values at prompts.

5. Edit the newly generated KFV file. Just move to the line of the entry you wish to edit and press Return.

a. If the entry is a file, the initial contents of the file are shown. For a file fitting entirely within its window, you are also prompted for a license shortcut code to enter. For longer files, you can scroll its window and when done examining the file, press Tab to return to the table and get prompted for a license code. Pressing Insert on a file entry prompts for a license code. To make a custom license entry for the file, just pick any shortcut and then later manually edit the generated markup, or use the special "custom" entry shortcut and later edit generated markup if needed.

b. If the entry is a directory, the kfv-start command will be run for the section associated with that directory. The other section that contained this entry is *not* deleted! Since "parent" directories ("..") are listed, they can be used to easily navigate among sections and subsections. This navigation is in addition to ordinary buffer switching shortcuts such as the C-x b shortcut. C-c C-u is another way to go from a section "up" to its parent.

If a file is found to be non-free, either by license or by the presence of non-free material such as non-free firmware, then its value in the column "All non-free SW reported" must be changed from "N/A" to either "N" or "Y", depending on whether you have reported this issue. (Of course, it can always be revised later if circumstances warrant.)

6. Press C-c twice when done editing to generate markup based on the edited table. If there are sections, subsections, etc., the best order to do this step is to generate markup for the deepest subdirectories first and then move up. This is because the parent directories will have their own tables generated that rely on information for subdirectory entries that is generated along with the markup for those subdirectories. An optimal order is "depth first search" so as to minimize the editing to markup that you have to do.

7. Inspect and touch up the generated markup for the wiki files. Either press C-c twice to automatically upload all of the generated files or just manually copy and paste data into the appropriate forms in a web browser. In particular, information on sections such as the "parent" section can be adjusted at the bottom and then used in an automated update of such sections.

An important kind of revision is to note the presence of non-free firmware, which effectively makes a file non-free, even if its license is free. This revision can be in the form of text additional to any markup that may exist for the offending file or as a footnote.

8. Markup for occasional "risky" pages is delimited by special lines. An important kind of risky page is parent pages. However, the only such markup that will be automatically uploaded is that occurring on the "highest" section page--such markup in subsection buffers will be ignored. Since parent pages tend to be riskier to mess up, special care is used in the upload of such a page. Immediately before the upload attempt, one last download attempt is made of the risky page. Only if no change is detected in this download versus an earlier download is the upload attempt made. (An upload of markup generated by the obsolete download might be out-of-date.)

9. If at any time you want to get rid of most of the buffers associated with KFV, run the kfv-kill-buffers command. It has no effect on saved data, i.e., files and directories.

10. After uploading data for a section, the file holding that data is marked as done by renaming it to end in ".posted". If you ever need to post data (e.g., revised data) for such a section again, you just need to remove the corresponding file ending in ".posted". Otherwise, your new data will always be ignored and never posted.

Notes

Requirements

Tips

Use the biggest Emacs frame possible. I have found that splitting a big frame into left and right halves with C-x 3 does a good job since you get to see more of the KFV buffer at a glance and, more importantly, you are almost certain to see all you need to see of introductory license info for file entries that are up onto the other half of the frame.

C-x 1 goes back to one window filling up the frame and is handy when inspecting the final markup of a section, since it reduces the need to scroll to see everything.

See TODO at the end of file, and feel free to make suggestions.

History

This software grew out of a earlier, more general effort at checking freedom of all software packages for gNewSense. Perhaps in the future both will be combined somehow indeed, it is easy to modify this file for any program besides the kernel.

KFV Mode releases:

 2008-07-04 0.8
 2008-04-26 0.7
 2008-04-18 0.6
 2008-04-17 0.5
 2008-04-06 0.4
 2008-04-02 0.3
 2008-03-31 0.2
 2008-03-28 0.1

Acknowledgements

Thanks to the gnewsense-users mailing list for comments on formatting issues, in particular Christophe Jarry and Marco Chieppa. Sam Geeraerts, Christophe Jarry, and Markus Laire have helped to catch bugs or suggest features.

Download


CategoryOutdated

Kernel/Kfv-script (last edited 2013-08-30 21:22:46 by FelipeLopez)