[issue45139] Docs: add source directive for minor translation simplification

[Raymond Hettinger]

Raymond Hettinger  added the comment:

New directives introduce complexity. They should be saved for pervasive and 
non-trivial problems.

The motivation for this change is dubious (that a translator can't easily 
handle a simple fixed string pattern).  The OP grants that this is a "only 
small burden".   In general, translation is a large, difficult and time 
consuming task.  Adding this directive would not change that noticeably 
(changing the source text is among the easiest and most trivial subtasks).  It 
may even make translators job more difficult because it entails knowing how to 
edit the directive as opposed to use basic knowledge to make a simple in-line 
text substitution.

OTOH, there are costs.  Every new directive takes time to learn and remember.  
This is especially problematic when the directives are specific to one project; 
otherwise, the documentation skills don't translate across projects.  
Generally, it is best to use dirt simple, standard Sphinx markup, especially 
for trivial tasks like this one.

I do a lot of documentation work and am constantly wrestling will sphinx, many 
times unsuccessfully. Even among core developers, very few people already know 
all the directives that we already have.  Making the list longer doesn't make 
our lives easier unless a directive is solves a challenging problem and is 
commonly used.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue45139] Docs: add source directive for minor translation simplification

[Zachary Ware]

Zachary Ware  added the comment:

Note that this is suggesting to introduce a `.. source` directive, not adjust 
the existing `:source:` role.

There's nothing preventing the use of the existing pattern in special cases, 
while using the new directive in the common cases.  I don't have context for 
how much effort this would actually save translators (perhaps we could get 
representatives from various languages/workflows could chime in?) so it might 
not be worth it on other grounds, but I don't think this should be shot down 
just for "but sometimes" :)

--
nosy: +zach.ware
title: Docs: More surrounding text into the "source" directive -> Docs: add 
source directive for minor translation simplification
type:  -> enhancement

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com