[vlc-devel] [PATCH 1/3] core: fix help output option categorization
Lyndon Brown
jnqnfe at gmail.com
Wed Sep 30 21:40:16 CEST 2020
preview
From: Lyndon Brown <jnqnfe at gmail.com>
Date: Sun, 3 Dec 2017 05:19:55 +0000
Subject: core: fix help output option categorization
When core options are printed in terminal help output, category headings
are only printed when a 'category hint' entry is encountered in the list.
As things were, some hints were missing or otherwise misplaced, such that
some options appeared mis-categorised. The preferences GUI interface is
unaffected. This commit corrects the problem.
The problem specifically consists of the following component issues:
- When we get to INPUT category options, no hint is given. The input cat
starts with a section called "track settings" and you can see that this
gets printed immediately after the section "overlays" from the
subpictures category; Thus it appears as though most input options are
actually subpicture options.
- Further down, the input sub-categories "vcodec" and "access" both have
hints (of "decoders" and "input" respectively), resulting in headings
being printed. But, for the latter, the title and longtext description
actually reflects a heading that should apply to the entire input
category. 'Decoders' as a heading for the VCodec sub-cat is wrong, and
the longtext (CODEC_CAT_LONGTEXT) is worded to speak of one single
option only.
- Further still, you may find a "Performance options" section heading,
but its location varies. It should appear under "Miscellaneous", but if
there are no options to display under it (i.e. when not showing advanced
options, and not on Windows), it thus appears instead under the
"Playlist" category heading. (Update: this point is somewhat outdated
now with --advanced having been removed in v4.0 dev subsequent to the
original creation of this commit).
- Next, when we get to the interface category, again no hint is given.
The playlist category above it ends with the "services-discovery"
option, but no title gets printed for the interface category, so it is
directly followed by the interface options, starting with "verbose".
Eventually we get a hint for the hotkeys interface sub-category and get
a new heading.
- Finally, we get a '-1' category, hiding some options from the GUI. This
illogially includes options like --help along with bookmark and
bookmark-hotkey options. Furthermore there is no hint, thus all of these
are appearing under the "hotkeys" heading, specifically in fact the
"Jump sizes" section.
This commit addresses these issues by:
- Moving the input category hint up to where that category actually starts.
- Moving the SUBCAT_INPUT_VCODEC subcat block to a more logical position.
- Changing the "Decoders" hint that starts the access/codec input options
to "Input access and codecs" and rewriting the longtext.
- Removing MISC_CAT_LONGTEXT which didn't make sense in context.
- Changing the "Miscellaneous" hint for the advanced category to
"Advanced" matching the category title in the (Qt) GUI.
- Moving the "--bookmark1", "--bookmark2", etc block of options that
relate to playlists up to the general playlist category, though retaining
the -1 subcat to ensure that they are still correctly hidden in the GUI.
(the individual options need hiding as they are separately found and
included in the big hotkey table control).
- Adding a hint for the interface category, so we get a heading now. (This
re-used the already existing longtext).
- Clarifying the comment (now duplicated) about hiding options with the -1
cat/subcat hack, by mentioning this relates to the GUI.
- Adding a "Bookmarks" section heading for bookmark hotkey options, to
separate these from the previous "Jump Sizes" section.
- Adding a "Miscellaneous" hint before the block at the end which includes
the help output options to create a new heading, separating this stuff
from the previous hotkeys (interface sub-cat) heading.
- Moving the -1 cat/subcat that was incorrectly above the bookmark-hotkey
options down to this misc block.
Also, I've moved the module name up to the top (clearer IMO).
diff --git a/src/libvlc-module.c b/src/libvlc-module.c
index 1cb548ff5f..11bd31d12e 100644
--- a/src/libvlc-module.c
+++ b/src/libvlc-module.c
@@ -949,9 +949,8 @@ static const char *const ppsz_prefres[] = {
// DEPRECATED
#define CODEC_CAT_LONGTEXT N_( \
- "This option can be used to alter the way VLC selects " \
- "its codecs (decompression methods). Only advanced users should " \
- "alter this option as it can break playback of all your streams." )
+ "These options allow you to control the preferred modules used for " \
+ "accessing, demuxing and decoding (or encoding) inputs." )
#define CODEC_TEXT N_("Preferred decoders list")
#define CODEC_LONGTEXT N_( \
@@ -1044,11 +1043,6 @@ static const char *const ppsz_prefres[] = {
* Advanced
****************************************************************************/
-// DEPRECATED
-#define MISC_CAT_LONGTEXT N_( \
- "These options allow you to select default modules. Leave these " \
- "alone unless you really know what you are doing." )
-
#define ACCESS_TEXT N_("Access module")
#define ACCESS_LONGTEXT N_( \
"This allows you to force an access module. You can use it if " \
@@ -1540,6 +1534,8 @@ static const char *const mouse_wheel_texts[] = {
*/
vlc_module_begin ()
+ set_description( N_("core program") )
+
/* Audio options */
set_category( CAT_AUDIO )
set_subcategory( SUBCAT_AUDIO_GENERAL )
@@ -1774,6 +1770,7 @@ vlc_module_begin ()
/* Input options */
set_category( CAT_INPUT )
set_subcategory( SUBCAT_INPUT_GENERAL )
+ add_category_hint( N_("Input"), INPUT_CAT_LONGTEXT )
set_section( N_( "Track settings" ), NULL )
add_integer( "program", 0,
@@ -2012,26 +2009,29 @@ vlc_module_begin ()
add_bool( "lua", true, INPUT_LUA_TEXT, INPUT_LUA_TEXT, true );
/* Decoder options */
- set_subcategory( SUBCAT_INPUT_VCODEC )
- add_category_hint(N_("Decoders"), CODEC_CAT_LONGTEXT)
- add_string( "codec", NULL, CODEC_TEXT,
- CODEC_LONGTEXT, true )
- add_bool( "hw-dec", true, HW_DEC_TEXT, HW_DEC_LONGTEXT, true )
- add_string( "encoder", NULL, ENCODER_TEXT,
- ENCODER_LONGTEXT, true )
- add_module("dec-dev", "decoder device", "any", DEC_DEV_TEXT, DEC_DEV_LONGTEXT)
-
+ add_category_hint(N_("Input access and codecs"), CODEC_CAT_LONGTEXT)
set_subcategory( SUBCAT_INPUT_ACCESS )
- add_category_hint(N_("Input"), INPUT_CAT_LONGTEXT)
+
add_module("access", "access", NULL, ACCESS_TEXT, ACCESS_LONGTEXT)
set_subcategory( SUBCAT_INPUT_DEMUX )
+
add_module("demux", "demux", "any", DEMUX_TEXT, DEMUX_LONGTEXT)
+
set_subcategory( SUBCAT_INPUT_ACODEC )
+ set_subcategory( SUBCAT_INPUT_VCODEC )
+
+ add_string( "codec", NULL, CODEC_TEXT, CODEC_LONGTEXT, true )
+ add_bool( "hw-dec", true, HW_DEC_TEXT, HW_DEC_LONGTEXT, true )
+ add_string( "encoder", NULL, ENCODER_TEXT, ENCODER_LONGTEXT, true )
+ add_module("dec-dev", "decoder device", "any", DEC_DEV_TEXT, DEC_DEV_LONGTEXT)
+
set_subcategory( SUBCAT_INPUT_SCODEC )
+
add_obsolete_bool( "prefer-system-codecs" )
set_subcategory( SUBCAT_INPUT_STREAM_FILTER )
+
add_module_list("stream-filter", "stream_filter", NULL,
STREAM_FILTER_TEXT, STREAM_FILTER_LONGTEXT)
@@ -2100,10 +2100,10 @@ vlc_module_begin ()
add_obsolete_bool( "altivec" ) /* since 2.0.0 */
#endif
-/* Misc options */
+/* Advanced options */
set_subcategory( SUBCAT_ADVANCED_MISC )
+ add_category_hint(N_("Advanced"), NULL)
set_section( N_("Special modules"), NULL )
- add_category_hint(N_("Miscellaneous"), MISC_CAT_LONGTEXT)
add_module("vod-server", "vod server", NULL,
VOD_SERVER_TEXT, VOD_SERVER_LONGTEXT)
@@ -2219,9 +2219,34 @@ vlc_module_begin ()
add_string( "services-discovery", "", SD_TEXT, SD_LONGTEXT, true )
change_short('S')
+ /* HACK so these don't get displayed in the GUI */
+ set_subcategory( -1 )
+ set_section(N_("Bookmarks"), NULL)
+ add_string( "bookmark1", NULL,
+ BOOKMARK1_TEXT, BOOKMARK_LONGTEXT, false )
+ add_string( "bookmark2", NULL,
+ BOOKMARK2_TEXT, BOOKMARK_LONGTEXT, false )
+ add_string( "bookmark3", NULL,
+ BOOKMARK3_TEXT, BOOKMARK_LONGTEXT, false )
+ add_string( "bookmark4", NULL,
+ BOOKMARK4_TEXT, BOOKMARK_LONGTEXT, false )
+ add_string( "bookmark5", NULL,
+ BOOKMARK5_TEXT, BOOKMARK_LONGTEXT, false )
+ add_string( "bookmark6", NULL,
+ BOOKMARK6_TEXT, BOOKMARK_LONGTEXT, false )
+ add_string( "bookmark7", NULL,
+ BOOKMARK7_TEXT, BOOKMARK_LONGTEXT, false )
+ add_string( "bookmark8", NULL,
+ BOOKMARK8_TEXT, BOOKMARK_LONGTEXT, false )
+ add_string( "bookmark9", NULL,
+ BOOKMARK9_TEXT, BOOKMARK_LONGTEXT, false )
+ add_string( "bookmark10", NULL,
+ BOOKMARK10_TEXT, BOOKMARK_LONGTEXT, false )
+
/* Interface options */
set_category( CAT_INTERFACE )
set_subcategory( SUBCAT_INTERFACE_GENERAL )
+ add_category_hint( N_("Interface"), INTF_CAT_LONGTEXT )
add_integer( "verbose", 0, VERBOSE_TEXT, VERBOSE_LONGTEXT,
false )
change_short('v')
@@ -2744,9 +2769,7 @@ vlc_module_begin ()
add_integer( "long-jump-size", 300, JILONG_TEXT,
JILONG_LONGTEXT, false )
- /* HACK so these don't get displayed */
- set_category( -1 )
- set_subcategory( -1 )
+ set_section ( N_("Bookmarks"), NULL )
add_key("key-set-bookmark1", KEY_SET_BOOKMARK1,
SET_BOOKMARK1_KEY_TEXT, SET_BOOKMARK_KEY_LONGTEXT)
add_key("key-set-bookmark2", KEY_SET_BOOKMARK2,
@@ -2797,26 +2820,11 @@ vlc_module_begin ()
add_key("key-subtitle-text-scale-down", KEY_SUBTEXT_SCALEDOWN,
SUBTEXT_SCALEDOWN_KEY_TEXT, SUBTEXT_SCALE_KEY_LONGTEXT)
- add_string( "bookmark1", NULL,
- BOOKMARK1_TEXT, BOOKMARK_LONGTEXT, false )
- add_string( "bookmark2", NULL,
- BOOKMARK2_TEXT, BOOKMARK_LONGTEXT, false )
- add_string( "bookmark3", NULL,
- BOOKMARK3_TEXT, BOOKMARK_LONGTEXT, false )
- add_string( "bookmark4", NULL,
- BOOKMARK4_TEXT, BOOKMARK_LONGTEXT, false )
- add_string( "bookmark5", NULL,
- BOOKMARK5_TEXT, BOOKMARK_LONGTEXT, false )
- add_string( "bookmark6", NULL,
- BOOKMARK6_TEXT, BOOKMARK_LONGTEXT, false )
- add_string( "bookmark7", NULL,
- BOOKMARK7_TEXT, BOOKMARK_LONGTEXT, false )
- add_string( "bookmark8", NULL,
- BOOKMARK8_TEXT, BOOKMARK_LONGTEXT, false )
- add_string( "bookmark9", NULL,
- BOOKMARK9_TEXT, BOOKMARK_LONGTEXT, false )
- add_string( "bookmark10", NULL,
- BOOKMARK10_TEXT, BOOKMARK_LONGTEXT, false )
+/* Miscellaneous */
+ /* HACK so these don't get displayed in the GUI */
+ set_category( -1 )
+ set_subcategory( -1 )
+ add_category_hint(N_("Miscellaneous"), NULL)
#define HELP_TEXT \
N_("print help for VLC (can be combined with --help-verbose)")
@@ -2881,7 +2889,6 @@ vlc_module_begin ()
add_string( "config", NULL, CONFIG_TEXT, "", false )
change_volatile ()
- set_description( N_("core program") )
vlc_module_end ()
/*****************************************************************************
More information about the vlc-devel
mailing list