Debian Codegraph @

doc/video_format.sgml

raw
1 <refentry id="video_format">
2
3 <refentryinfo>
4 <address>
5 &dhemail;
6 </address>
7 <author>
8 &dhfirstname;
9 &dhsurname;
10 </author>
11 <copyright>
12 <year>2016</year>
13 <holder>&dhusername;</holder>
14 </copyright>
15 &dhdate;
16 </refentryinfo>
17 <refmeta>
18 <refentrytitle>video_format</refentrytitle>
19 <manvolnum>7</manvolnum>
20 </refmeta>
21
22 <refnamediv>
23 <refname>video_format</refname>
24 <refpurpose>
25 Proposal For A Video Format Preference Specification
26 </refpurpose>
27 </refnamediv>
28
29 <refsect1>
30 <title>DESCRIPTION</title>
31 <para>
32 A number of different programs that create or work with video material need to know whether to generate their output in NTSC or PAL format. The ones that I’ve seen seem to have a hard-coded preference for one unless the user specifies the other. Overriding the default every time you want to use these programs gets tiresome.
33 </para>
34 <para>
35 Therefore, there needs to be a way for the user to configure a single default that will apply to all these programs. This default should be settable on a per-user basis and a systemwide basis, with the per-user setting overriding the systemwide one, as is usual. It makes sense to avoid dotfile clutter by following, at least to some extent, the XDG Base Directory Specification <uri>http://standards.freedesktop.org/basedir-spec/latest/</uri>.
36 </para>
37 <para>
38 The preference setting shall consist of the single word “NTSC” or “PAL” (without quotes, might as well be case-insensitive). This can be specified in the following ways, in order of decreasing priority:
39 <itemizedlist mark="opencircle">
40 <listitem><para>
41 As the value of the environment variable <literal>VIDEO_FORMAT</literal>
42 </para></listitem>
43 <listitem><para>
44 As the contents of the user-specific file <literal>$XDG_CONFIG_HOME/video_format</literal>, with <literal>$XDG_CONFIG_HOME</literal> defaulting to <literal>$HOME/.config</literal> if not defined.
45 </para></listitem>
46 <listitem><para>
47 As the contents of a systemwide file <replaceable>dir</replaceable><literal>/video_format</literal>, where <replaceable>dir</replaceable> is taken in turn from the colon-separated items in the value of <literal>$XDG_CONFIG_DIRS</literal> until the file is found, or if <literal>$XDG_CONFIG_DIRS</literal> is not defined, then the single directory <literal>/etc</literal>.
48 </para></listitem>
49 </itemizedlist>
50 </para>
51 <para>
52 The application should use the first of these settings that it finds, searching in the specified order.
53 </para>
54 <para>
55 <emphasis>Note:</emphasis> the XDG Base Dir spec says systemwide config files should go in <literal>/etc/xdg</literal>. I'm not sure why this is, since lots of other apps put systemwide config in other places in <literal>/etc</literal>. Particularly since the spec doesn’t similarly restrict shared read-only data to just one subdirectory of <literal>/usr/share</literal>.
56 </para>
57 </refsect1>
58 <refsect1>
59 <title>DISCUSSION</title>
60 <para>
61 Can this spec apply to both standard-definition and high-definition video? For standard definition, there is a difference of frame size, being 720 by 480 for NTSC and 720 by 576 for PAL (in both cases, the aspect ratio of the displayed image is always 4:3). But this doesn’t seem to matter for high definition. For both standard-definition and high-definition, there is a difference of frame rates, based around 29.97 fps for NTSC and 25 fps for PAL.
62 </para>
63 <para>
64 Note also that if a config file earlier in the search contains an invalid setting, the search does not continue even if another, later config file might contain a valid setting. This allows the user to override a system default with “no default”. Is this important? I think it could be.
65 </para>
66 </refsect1>
67
68 <refsect1>
69 <title>REFERENCE IMPLEMENTATION</title>
70 <para>
71 The following Python code implements a routine called <literal>get_default_video_format</literal> that returns either one of the strings “NTSC” or “PAL” indicating the user/system-configured default format as per the spec above, or <literal>None</literal> if the default is invalid or not configured.
72 </para>
73 <programlisting><![CDATA[
74 class xdg_base_dir :
75 "Implementation of relevant parts of the XDG Base Directory specification" \
76 " <http://standards.freedesktop.org/basedir-spec/latest/>."
77 @classmethod
78 def get_config_home(self) :
79 "returns the directory for holding user-specific config files."
80 result = os.environ.get("XDG_CONFIG_HOME")
81 if result == None :
82 result = os.path.join(os.environ["HOME"], ".config")
83 #end if
84 return result
85 #end get_config_home
86
87 @classmethod
88 def config_search_path(self) :
89 "returns the list of config directories to search (apart from the user area)."
90 return tuple(os.environ.get("XDG_CONFIG_DIRS", "/etc").split(":"))
91 # note spec actually says default should be /etc/xdg, but /etc is the
92 # conventional location for system config files.
93 #end config_search_path
94
95 @classmethod
96 def find_first_config_path(self, path) :
97 "searches for path in all the config directory locations in order of decreasing" \
98 " priority, returning the expansion where it is first found, or None if not found."
99 paths_to_try = iter((self.get_config_home(),) + self.config_search_path())
100 # highest priority first
101 while True :
102 this_path = next(paths_to_try, None)
103 if this_path == None :
104 break
105 this_path = os.path.join(this_path, path)
106 if os.path.exists(this_path) :
107 break
108 #end while
109 return this_path
110 #end find_first_config_path
111
112 #end xdg_base_dir
113
114 valid_video_formats = frozenset(("NTSC", "PAL"))
115
116 def get_default_video_format() :
117 video_format = os.environ.get("VIDEO_FORMAT")
118 if video_format == None :
119 config_file = xdg_base_dir.find_first_config_path("video_format")
120 if config_file != None :
121 try :
122 video_format = open(config_file, "r").readline().strip()
123 except OSError :
124 video_format = None
125 #end try
126 #end if
127 #end if
128 if video_format != None :
129 video_format = video_format.upper()
130 if video_format not in valid_video_formats :
131 video_format = None
132 #end if
133 #end if
134 return video_format
135 #end get_default_video_format
136 ]]></programlisting>
137 </refsect1>
138 </refentry>